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.