OIDC Authenticator for Conjur UI and Conjur CLI authentication

Use the OIDC Authenticator to enable users to sign in to the Conjur UI or Conjur CLI using your organization's existing identity provider (IdP) implementation. This enhances security and product experience for organizations that require single sign-on (SSO) and multi-factor authentication (MFA).

While the OIDC Authenticator for the Conjur UI and the Conjur CLI are similar, you must deploy them as separate authenticators to enable OIDC authentication to both the UI and CLI.

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

You must run the Conjur CLI directly on the user's machine in order to use OIDC authentication. The Conjur CLI cannot use OIDC authentication if it is deployed inside a Docker container or other headless environment.

  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
       
        # CA Cert [Optional] - Defines a CA cert/chain to use for TLS verification with the provider
        - !variable ca-cert
      
        # 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.

    ca-cert

    (Optional) The CA certificate or concatenated certificate chain used to configure a trusted TLS connection from Conjur to the OIDC provider. You can also use this to enable connections through a proxy that uses a private certificate authority.

    The default behavior is to use the same CA truststore as the Conjur container, which is suitable in most cases.

    If set, the value must contain the full certificate chain required to connect to the OIDC provider. No certificates included in the system's default store are considered.

    The following example demonstrates setting a value to ca-cert by a user authenticated to the Conjur CLI and using OpenSSL. The hostname cannot include an HTTP/HTTPS prefix.

    # Fetch the certificate chain via OpenSSL and write to a file
    openssl s_client -showcerts -connect "$provider_hostname:443" < /dev/null | awk '/-----BEGIN CERTIFICATE-----/,/-----END CERTIFICATE-----/' > cert_chain.pem
    
    # Set the Conjur variable
    conjur variable set --id "conjur/authn-oidc/$service_id/ca-cert" --value "$(cat cert_chain.pem)"

    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.

Logging out of the Conjur UI or CLI does not log the user out from the OIDC provider.

  1. The application sends a request to Conjur to retrieve a list of available OIDC providers.

  2. The application presents the list of providers to the user.

  3. The user selects the provider they are authorized to use and the application directs them to the provider's sign-in page.

  4. After the user successfully signs in, the OIDC application redirects the user to the URL specified in the redirect-uri variable with a code and state for the request.

    1. The application receives the redirect request, verifies that the state value matches the value generated during the provider redirect, then makes a request to Conjur with the retrieved code along with the generated PKCE and nonce values.

    2. Conjur verifies the retrieved code and performs back-channel authentication with the OIDC provider using the provided nonce and PKCE values.

    3. Conjur returns an access token to the user-facing application in the response.

  1. The user calls the conjur init command from the CLI specifying the authn-type of oidc and the service-id of the OIDC provider.
  2. The Conjur CLI directs the user to the provider's sign-in page.

  3. After the user successfully signs in, the OIDC application redirects the user to the URL specified in the redirect-uri variable with a code and state for the request.

    1. The application receives the redirect request, verifies that the state value matches the value generated during the provider redirect, then makes a request to Conjur with the retrieved code along with the generated PKCE and nonce values.

    2. Conjur verifies the retrieved code and performs back-channel authentication with the OIDC provider using the provided nonce and PKCE values.

    3. Conjur returns an access token to the user-facing application in the response.

Custom token TTL

Token TTL is only configurable for the OIDC Authenticator for the Conjur UI and CLI v8.x. You cannot set a custom token TTL for OIDC authentication for applications or any other Conjur access tokens.

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 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.

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.

The duration of Conjur access tokens for OIDC authentication take the following order of precedence:

  1. The token-ttl variable

  2. System settings such as the host_authorization_token_ttl configuration setting

  3. The default duration of one hour