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.
Overview
What You'll Need¶
- A configured management environment.
- A running Rok Registry cluster.
- A social provider where you can create applications.
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 |
|
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¶
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
Extend
kustomization.yaml
to include the above patch:... patchesStrategicMerge: ... - patches/rokregistrycluster-enable-social-provider.yaml
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¶
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 chosengitlab
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
Extend
kustomization.yaml
to include the above patch:... patchesStrategicMerge: ... - patches/rokregistrycluster-configure-social-provider.yaml
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¶
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
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
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)¶
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
Extend
kustomization.yaml
to include the above patch:... patchesStrategicMerge: ... - patches/rokregistrycluster-allow-email-symbols.yaml
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.