Rok Registry Authentication

This guide will walk you through configuring external OIDC providers for authentication in Rok Registry. From now on, we will refer to these providers as social providers.

What You’ll Need

Configuration Settings

Below you can find a list of the configuration settings for social providers.

Setting Format Description
name String A user-friendly name for the provider. This value is displayed in the login page of Rok Registry.
type String The type of this provider. The value of this field will determine the default values that will be used for the optional fields. Currently, generic is the only provider type we support.
client_id String The client ID given by the social provider when registering the application.
client_secret String The client secret given by the social provider when registering the application.
issuer_root_endpoint String The endpoint for the OIDC discovery mechanism. This field is optional.
authorization_endpoint token_endpoint userinfo_endpoint String The endpoints to perform the OIDC code authentication flow and retrieve information about the authenticated user. If no issuer root endpoint is given, then these three endpoints must be defined.
mapping Dictionary Mapping between the social provider claims and the standard OIDC claims. This field is optional.
scopes List of strings The scopes Rok Registry will request when authenticating the user with the external provider. This field is optional. The ‘openid’ scope is implied.
assume_email_verified Boolean Whether to assume that the user email is verified. This should be set to true when the social provider doesn’t support email verification. This field is optional.

Configure Social Providers

To use social providers for authenticating your users in Rok Registry, you have to properly setup your deployment manifests. The following paragraphs describe the steps to do so.

1. Register an Application

First register an application with the social provider, in order to setup the callback URL and scopes and get your client credentials. The callback URL should have the following form:

HOST/oidc-callback/PROVIDER_ID

HOST is the endpoint where you expose Rok Registry and PROVIDER_ID is an identifier for the social provider. You can set this identifier arbitrarily, but note that you will use it later on when configuring the social provider. In addition, if you are adding multiple social providers, PROVIDER_ID must be unique for each one.

About the necessary scopes, Rok Registry needs to authenticate users and access their email, so ensure you grant the proper scopes to allow these operations.

For example, if you use GitLab as a social provider, expose Rok Registry at https://demo.example.com/registry, and choose gitlab as the identifier for the social provider (PROVIDER_ID), you can go to Admin area -> Applications -> New Application and use the following settings to register an application:

Callback URL https://demo.example.com/registry/oidc-callback/gitlab
Trusted No
Confidential Yes
Scopes
  • openid (Authenticate using OpenID Connect)
  • email (Allow read-only access to the user’s primary email address)

2. Edit Manifests

Change your current directory to the local clone of Arrikto’s deployments GitOps repository and go into the deploy overlay of Rok Registry. For example:

root@rok-tools:/# cd ~/ops/deployments/rok/rok-registry-cluster/overlays/deploy

Enable the Social Authentication Method

  1. Create the patches/rokregistrycluster-enable-social-provider.yaml patch and add the following:

    apiVersion: crd.arrikto.com/v1alpha1
    kind: RokRegistryCluster
    metadata:
      name: rok-registry
    spec:
      configVars:
        fort.auth_methods: social
    
  2. Extend kustomization.yaml to include the above patch:

    ...
    patchesStrategicMerge:
      ...
      - patches/rokregistrycluster-enable-social-provider.yaml
    
  3. Stage changes for commit:

    root@rok-tools:~/ops/deployments/rok/rok-registry-cluster/overlays/deploy# git add kustomization.yaml patches/rokregistrycluster-enable-social-provider.yaml
    

Configure Social Providers

  1. Create the patches/rokregistrycluster-configure-social-provider.yaml patch and add the configuration for the social providers you want to support. For example, if you are using GitLab as a social provider and assuming you have chosen gitlab for the provider identifier, you can add something like the following:

    apiVersion: crd.arrikto.com/v1alpha1
    kind: RokRegistryCluster
    metadata:
      name: rok-registry
    spec:
      socialProviders:
        gitlab:
            name: GitLab
            type: generic
            client_id: YOUR_CLIENT_ID
            issuer_root_endpoint: "https://gitlab.com"
            scopes:
            - email
    
  2. Extend kustomization.yaml to include the above patch:

    ...
    patchesStrategicMerge:
      ...
      - patches/rokregistrycluster-configure-social-provider.yaml
    
  3. Stage changes for commit:

    root@rok-tools:~/ops/deployments/rok/rok-registry-cluster/overlays/deploy# git add kustomization.yaml patches/rokregistrycluster-configure-social-provider.yaml
    

Configure Client Secrets

Create the secrets/social_provider_credentials file and add the client secret for each social provider that you use. This file follows the environment format. For example, assuming gitlab is the social provider identifier:

gitlab=YOUR_CLIENT_SECRET

Create the Secret Generator

  1. Create the patches/rokregistrycluster-social-provider-credentials-secret.yaml patch and add the following:

    apiVersion: crd.arrikto.com/v1alpha1
    kind: RokRegistryCluster
    metadata:
      name: rok-registry
    spec:
      socialProviderCredentialsSecret: rok-registry-social-provider-credentials-secret
    
  2. Extend kustomization.yaml to include the above patch and add the secret generator:

    secretGenerator:
      ...
      - name: rok-registry-social-provider-credentials-secret
        envs:
        - secrets/social_provider_credentials
        type: Opaque
    ...
    patchesStrategicMerge:
      ...
      - patches/rokregistrycluster-social-provider-credentials-secret.yaml
    
  3. Stage changes for commit:

    root@rok-tools:~/ops/deployments/rok/rok-registry-cluster/overlays/deploy# git add kustomization.yaml patches/rokregistrycluster-social-provider-credentials-secret.yaml
    

Allow Email Symbols (optional)

  1. By default, Rok Registry does not allow email symbols in usernames (‘.’, ‘@’, ‘+’). If such symbols appear in usernames, then login will fail. To allow email symbols, create the patches/rokregistrycluster-allow-email-symbols.yaml patch and add the following:

    apiVersion: crd.arrikto.com/v1alpha1
    kind: RokRegistryCluster
    metadata:
      name: rok-registry
    spec:
      configVars:
        fort.allow_email_symbols: true
    
  2. Extend kustomization.yaml to include the above patch:

    ...
    patchesStrategicMerge:
      ...
      - patches/rokregistrycluster-allow-email-symbols.yaml
    
  3. Stage changes for commit:

    root@rok-tools:~/ops/deployments/rok/rok-registry-cluster/overlays/deploy# git add kustomization.yaml patches/rokregistrycluster-allow-email-symbols.yaml
    

3. Commit Changes

Once you are done modifying the deployment manifests you can commit changes locally:

root@rok-tools:~/ops/deployments# git commit -m "Configure social providers for Rok Registry"

Note

Optionally, you can push your local changes to a remote of your choice.

4. Apply changes

In order to apply the desired state to Kubernetes you need to re-apply the deployment manifests that you previously edited.

You can re-apply all of the manifests automatically with:

root@rok-tools:~/ops/deployments# rok-deploy --apply install/registry

Alternatively, you can apply only the manifests you changed:

root@rok-tools:~/ops/deployments# rok-deploy --apply rok/rok-registry-cluster/overlays/deploy

Summary

You have successfully configured social providers in Rok Registry for authenticating your users.

What’s Next

You can continue to the Expose Services section to expose Rok Registry to the outside world.