OIDC Authenticator for Conjur UI and Conjur CLI authentication

Supported OIDC providers

• The OIDC Authenticator for Conjur UI and Conjur CLI uses OIDC interfaces that are well defined in the OpenID Connect Core 1.0 and OpenID Connect Discovery 1.0 specifications and supports any OIDC provider that faithfully implements these interfaces.

• The OIDC Authenticator for Conjur UI and Conjur CLI does not use or support functionality described in any other specification, draft or accepted.

• The OIDC Authenticator for Conjur UI and CLI has been thoroughly tested only against CyberArk Identity, Okta, and Keycloak.

How does it work?

1. The Admin creates an authentication policy definition and assigns a user to that authentication group.

2. The user does one of the following:

   • Visits the Conjur UI sign-in page and selects an available OIDC authentication method.

   • Initializes the Conjur CLI using the init command with the --authn-type of oidc and the --service-id of the OIDC authentication service.

3. Conjur redirects the user to the OIDC provider's sign-in page. When authenticating to the Conjur CLI, Conjur opens a browser window.

   The Conjur CLI must have the ability to open a browser window in order to use OIDC authentication.

4. After the user successfully signs in, the OIDC application redirects the user to the Conjur UI or Conjur CLI with an authorization code.

5. The application sends the authorization code to Conjur.

6. Conjur exchanges the authorization code for an access token and verifies that the user exists and has permission to access the Conjur UI or Conjur CLI.

7. Conjur sends a Conjur access token to the Conjur UI.

For more information, see Conjur UI and CLI authentication flow.

Configure the OIDC Authenticator to enable sign-in to the Conjur UI or Conjur CLI

1. Prerequisite: Define Conjur resources (users and variables), and grant necessary permissions

   The main purpose of OIDC authentication is to grant access tokens to application components authenticating with an ID token of a user. Before configuring OIDC authentication, ensure that the necessary users and variables exist and that the users have been given permissions to use those variables.

   • You create variables and assign users permissions to them using policy.
   • You create users using policy.

   In the following example, the policy defines an application with a variable, required-var, and a group of users, users, which are permitted to use that variable. It also creates a user, alice, and adds it to the users group.

   - !policy
     id: the-application
     body:
     - !user alice
     - !group users
   
     - !grant
        role: !group users
        members:
        - !user alice
   
     - !variable required-var
   
     - !permit
       role: !group users
       privilege: [ read, execute ]
       resource: !variable required-var

2. Define the OIDC Authenticator

   The OIDC Authenticator uses a policy to define the authenticator configuration settings and access permissions.

   All OIDC Authenticator configurations begin with the policy ID prefix conjur/authn-oidc.

   A Conjur Server can also use multiple instances of the same authenticator type. For example, you might have more than one OIDC Provider. Each instance is a separate service.

   To identify each service, append a service ID to the authenticator type throughout the configuration. Use the same service ID consistently in the configuration. For example, for a CyberArk Identity OIDC Provider, the service ID can be identity.

   Create the required policy defining the OIDC Authenticator.

   1. Copy the following policy and, in the policy's ID, provide the service ID of your OIDC Provider:

      - !policy id: conjur/authn-oidc/<service-id> body: - !webservice - !variable token-ttl - !variable provider-uri - !variable client-id - !variable client-secret # Token TTL [Optional] - Use this to override default - !variable token-ttl # URI of Conjur instance - !variable redirect-uri # Defines the JWT claim to use as the Conjur identifier - !variable claim-mapping # Name [Optional] - Defines Name to display in Conjur-UI - !variable name # Provider-Scope [Optional] - Defines claim scope ie: openid email profile - !variable provider-scope # Status Webservice for authenticator - !webservice id: status annotations: description: Status service to check that the authenticator is configured correctly - !group id: operators annotations: description: Group of users who can check the status of the authenticator - !permit role: !group operators privilege: [ read ] resource: !webservice status - !group id: users annotations: description: Group of users who can authenticate using the authn-oidc/<service-id> authenticator - !permit role: !group users privilege: [ read, authenticate ] resource: !webservice #--- # Need to grant user members to role - !grant members: - !user testuser1@mycompany.com role: !group conjur/authn-oidc/<service id>/users

   2. Save the policy as a .yml file using the following file naming convention: authn-oidc-<service-id>.yml
   3. Load the policy file into any level below root:

      conjur policy load -b root -f authn-oidc-<service-id>.yml

3. Set values for the variables in the policy

   In the policy loaded above, the OIDC Authenticator uses the following variables that define its configuration:

   Variable name	Description
   provider-uri	The URL of the OIDC provider to redirect users to for authentication. This value is also needed during the IdP configuration. For example: https://example.com/oauth2/default
   client-id	The OIDC application's client ID, usually set during app creation
   client-secret	The OIDC application's client secret, usually set during app creation
   token-ttl	(Optional) The duration of the tokens distributed by an authenticator instance using the ISO-8601 duration format of P<date>T<time>. The default token-ttl for OIDC authentication is one hour and the maximum value is five hours. For example, use PT2H to set the value to two hours or PT5M to set the value to five minutes. The default duration of one hour applies only to Conjur access tokens used for OIDC authentication. The default duration for Conjur access tokens used with other authentication types remains eight minutes. For more information about the customizable token time to live (TTL), see Custom token TTL.
   redirect-uri	The URL that the OIDC application should redirect to after successful authentication. This is usually not Conjur, but instead an application that uses Conjur for authentication, such as the Conjur UI. For authentication to the Conjur CLI, the value is always http://127.0.0.1:8888/callback. For authentication to the Conjur UI, an example value is: https://localhost:443/ui/authn-oidc/identity/callback
   claim-mapping	List of space-delimited claims to which the client requests access from the OIDC provider.
   name	(Optional) The name to display on the Conjur UI sign-in page.
   provider-scope	(Optional) Additional scopes to retrieve on the provider-issued JWT. These scopes are added to the default set: openid email profile.

   For more details, see Setting variable values.

4. Enable Conjur users to authenticate using the OIDC Authenticator

   Users must exist in the root policy branch.

   1. Use the following policy as an example, replacing the user, role, and member as needed:

      - !user alice@mycompany.com - !grant role: !group conjur/authn-oidc/identity/users member: !user alice@mycompany.com

   2. Save the policy as a .yml file using the following file naming convention: authn-oidc-<service-id>-users.yml

   3. Load the policy file at root level:

      conjur policy load -b root -f authn-oidc-<service-id>-users.yml

5. Enable the OIDC Authenticator

   In this step, you enable the OIDC Authenticator on every Conjur Server you authenticate to with OIDC.

   To enable the OIDC Authenticator you need to allowlist it in Conjur. For details, see Allowlist the authenticators.

   The value for this variable should be identical to the name given to the policy ID above, excluding the conjur/ prefix. For example, to allowlist the CyberArk Identity OIDC Provider endpoint conjur/authn-oidc/identity, allowlist authn-oidc/identity.

6. Check the authenticator status

   Check that the authenticator is configured correctly. For details, see Authenticator Status Webservice.

Conjur UI and CLI authentication flow

The following flow represents how a user signs in to the Conjur UI or Conjur CLI using the OIDC Authenticator. This flow assumes that the Conjur UI or Conjur CLI is between the user and Conjur and is using Conjur with OIDC as the method of authentication with the Conjur UI or CLI.

Custom token TTL

You can change the Conjur access token duration from the default value of one hour using a custom token TTL variable. A shorter token duration may increase security but result in the need to re-authenticate frequently. A longer token duration may improve user experience, but as Conjur access tokens are irrevocable bearer tokens, this can reduce system security. We recommend balancing user experience and system security by extending the token TTL to the shortest acceptable time for your organization. You can change the default access token duration using the token-ttl variable.

The maximum duration of the token TTL is five hours. Conjur uses this maximum value for any OIDC Authenticator instance configured with a duration of longer than five hours.

If a user authenticates to the Conjur UI using an OIDC provider and logs out of the UI before their OIDC session expires, additional authentication requests from the same browser can be approved without requiring valid credentials. For this reason, an OIDC provider serving a Conjur UI instance should either be configured to expire sessions very quickly or enforce a multi-factor requirement on each authentication request.

To update an existing OIDC authenticator instance that uses default TTL behavior, first update the conjur/authn-oidc/<service_id> policy branch to create the token-ttl variable, then set the secret value to the desired TTL.