Set up Authentication
This document explains how to configure authentication types supported by Carthago Operator for Jenkins.
Authentication mechanisms listed below are unavailable in the free plan.
Use your GitHub organisation to authenticate in Jenkins.
In order to use GitHub OAuth, you need to install github-oauth plugin. The Carthago Operator will look for its declaration in the Jenkins Custom Resource.
First register your Jenkins in your GitHub organisation according to GitHub docs.
- Homepage URL is the root to the Jenkins UI url (eg. http://localhost:8080)
- Authorization callback URL provide the root to the Jenkins UI url with trailing “/securityRealm/finishLogin” (eg. “http://localhost:8080/securityRealm/finishLogin”)
Copy the clientSecret for use in the Carthago Operator and the clientID. You will need them in the next steps.
Prepare a secret resource with the client secret acquired from GitHub in the Jenkins namespace. Connect the secret to the JenkinsAuthentication Custom Resource via label.
apiVersion: v1
kind: Secret
metadata:
namespace: <jenkins-namespace>
name: github-client-secret
labels:
"carthago.cloud/jenkinsauthentication" : "github-oauth"
stringData:
clientSecret: <client-secret-from-GitHub>
Create it in the Kubernetes:
$ kubectl apply -f githubSecret.yaml
Next prepare the JenkinsAuthentication Custom Resource:
apiVersion: carthago.cloud/v1beta1
kind: JenkinsAuthentication
metadata:
name: github-oauth
namespace: <jenkins-namespace>
labels:
carthago.cloud/jenkins: example
spec:
type: "githubOAuth"
githubOAuth:
clientSecretRef:
namespace: <jenkins-namespace>
name: github-client-secret
clientID: <clientID-from-GitHub>
Create the JenkinsAuthentication Custom Resource in the Kubernetes:
$ kubectl apply -f jenkins-authentication.yaml
Additionally, you can specify different permission scopes. More information about different scopes can be found here. By default, the Carthago Operator sets these to “read:org” and “user:email”.
If you are using GitHub enterprise you can specify APIURI and WebURI. More information can be found in the GitHubOAuthAuthenticationConfig section of the schema
Use your Google organisation to authenticate in Jenkins.
In order to use GoogleHub OAuth, you need to install google-login plugin. The Carthago Operator will look for its declaration in the Jenkins Custom Resource.
Go to the GCP console.
If you do not have a project for Jenkins, you will need to create one. You will need to create an OAuth consent screen in the project.
Next, create credentials for Jenkins.
Click the +CREATE CREDENTIALS button and select OAuth client ID.
You will need to provide the main Jenkins URI and the redirect URI. Redirect URI is the URI with trailing “/securityRealm/finishLogin”.
Click “CREATE” and copy the Client Secret and the Client ID from the pop up window. You will need them in the next steps.
Prepare a secret resource with the client secret acquired from GitHub in the Jenkins namespace. Connect the secret to the JenkinsAuthentication Custom Resource via label.
apiVersion: v1
kind: Secret
metadata:
namespace: <jenkins-namespace>
name: google-client-secret
labels:
"carthago.cloud/jenkinsauthentication" : "google-oauth"
stringData:
clientSecret: <client-secret-from-GCP>
Create it in the Kubernetes:
$ kubectl apply -f googleSecret.yaml
Next, prepare the JenkinsAuthentication Custom Resource:
apiVersion: carthago.cloud/v1beta1
kind: JenkinsAuthentication
metadata:
name: google-oauth
namespace: <jenkins-namespace>
labels:
carthago.cloud/jenkins: example
spec:
type: "googleOAuth"
googleOAuth:
clientSecretRef:
namespace: <jenkins-namespace>
name: google-client-secret
clientID: <clientID-from-GCP>
domain: ""
Note: If you are using localhost you do not have to provide the domain field at all. Use this field if you have a public domain for your Jenkins.
Create the JenkinsAuthentication Custom Resource in the Kubernetes:
$ kubectl apply -f jenkins-authentication.yaml
More information can be found in the GoogleOAuthAuthenticationConfig section of the schema
Use various identity providers compliant with OpenID Connect standard.
In order to use OpenID Connect Auth, you need to install oic-auth plugin. To do that, you can refer to (configuring plugins section) of Customize Jenkins documentation page.
Prepare a secret resource with the client secret acquired from your identity provider in the Jenkins namespace. Connect the secret to the JenkinsAuthentication Custom Resource via label.
apiVersion: v1
kind: Secret
metadata:
namespace: <jenkins-namespace>
name: open-id-connect-secret
labels:
"carthago.cloud/jenkinsauthentication" : "openIDConnectAuth"
stringData:
clientSecret: <client-secret-from-identity-provider>
Create it in the Kubernetes:
$ kubectl apply -f openIDSecret.yaml
Next, prepare the JenkinsAuthentication Custom Resource, specifying either auto or manual configuration.
Below you can find the minimal set of configured variables required to work with OpenID Connect Authentication with automatic configuration. Note that with this mode of configuration, you have to specify the well-known OpenID configuration URL.
apiVersion: carthago.cloud/v1beta1
kind: JenkinsAuthentication
metadata:
name: open-id-connect-auth
namespace: <jenkins-namespace>
labels:
carthago.cloud/jenkins: example
spec:
type: "openIDConnectAuth"
openIDConnectAuth:
clientID: <client-id-from-identity-provider>
clientSecretRef:
namespace: <jenkins-namespace>
name: open-id-connect-secret
autoManualConfigure: auto
wellKnownOpenIDConfigurationURL: <well-known-configuration-url-from-identity-provider>
Alternatively, you can use manual configuration mode. In this case, you need to specify at minimum the URL of the token server and URL of the authorization server. Below you can find sample yaml with minimal configuration.
apiVersion: carthago.cloud/v1beta1
kind: JenkinsAuthentication
metadata:
name: open-id-connect-auth
namespace: <jenkins-namespace>
labels:
carthago.cloud/jenkins: example
spec:
type: "openIDConnectAuth"
openIDConnectAuth:
clientID: <client-id-from-identity-provider>
clientSecretRef:
namespace: <jenkins-namespace>
name: open-id-connect-secret
autoManualConfigure: manual
tokenServerURL: <token-server-url-from-identity-provider>
authorizationServerURL: <authorization-server-url-from-identity-provider>
SAML is an open standard for authentication. You can use it to integrate Jenkins auth with one many Identity Providers like Azure Active Directory, Okta, Auth0, and more.
In order to use SAML Auth, you need to install saml plugin. To do that, you can refer to (configuring plugins section) of Customize Jenkins documentation page.
Below you can find an example on how to configure SAML (Auth0 as an Identity Provider) via JenkinsAuthentication Custom Resource:
apiVersion: carthago.cloud/v1beta1
kind: JenkinsAuthentication
metadata:
name: saml
namespace: <jenkins-namespace>
labels:
carthago.cloud/jenkins: example
spec:
type: "samlAuth"
samlAuth:
idpMetadataURL: <idp-metadata-url>
logoutURL: <logout-url>
dataBindingMethod: http-post
usernameCaseConversion: none
refreshPeriod: 1
For all configuration options see our helm chart.