OpenID Connect (OIDC) Authenticator

CyberArk's OpenID Connect (OIDC) Authenticator leverages the identity layer provided by OIDC to facilitate the following use cases:

  • OIDC Authenticator for application authentication: CyberArk's OIDC Authenticator leverages the identity layer provided by OIDC to allow applications to authenticate with Conjur and retrieve secrets needed for connecting to services such as a database.

  • OIDC Authenticator for Conjur UI authentication: Use the OIDC Authenticator to enable users to sign in to the Conjur UI 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).

OpenID Connect (OIDC) is an identity layer on top of the OAuth 2.0 protocol that allows clients, including Web-based, mobile, and JavaScript clients, to request and receive information about authenticated sessions and end-users. Its purpose is to give an end-user one login to multiple applications.

 

To learn more about OpenID Connect, see the OpenID Connect website.

OIDC Authenticator for application authentication

How does it work?

  1. A user logs into an application.

  2. The application uses the OIDC Provider to authenticate the user. For details, see OpenID Connect.

  3. If the user is authenticated, the OIDC Provider sends back an ID Token.

  4. The application sends out the ID Token to other application components or microservices.

  5. When an application component needs to retrieve a secret from Conjur, it authenticates with Conjur using the ID Token it received from the OIDC Provider.

  6. Conjur sends an access token to the application component.

  7. The application component uses the access token to retrieve secrets and perform other actions in Conjur.

For more information, see OpenID Connect (OIDC) Authenticator.

Configure the OIDC Authenticator

This section describes how to set up the OIDC Authenticator to enable users to sign in to an application through Conjur using OIDC. To configure the OIDC Authenticator to enable users to sign in to the Conjur UI using OIDC, see Configure the OIDC Authenticator to enable sign in to the Conjur UI.

  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 can create variables and assign users permissions to them using policy.
    • You can create users using policy.

    In the following example, the policy defines an application with a variable, required-var, and a group of users, users, that 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 an Okta OIDC Provider, the service ID can be okta.

    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
          annotations:
            description: Authentication service for <service-id>, based on OpenID Connect.
       
        - !variable
          id: provider-uri
       
        - !variable
          id: id-token-user-property
       
        - !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
    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.

  3. Set values for the variables in the policy.

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

    Use the following commands to set values for these variables:

     
    conjur variable set -i conjur/authn-oidc/<service-id>/provider-uri -v <provider-uri value>
    conjur variable set -i conjur/authn-oidc/<service-id>/id-token-user-property -v <id-token-user-property value>
     
    conjur variable values add conjur/authn-oidc/<service-id>/provider-uri <provider-uri value>
    conjur variable values add conjur/authn-oidc/<service-id>/id-token-user-property <id-token-user-property value>

    Variable name

    Description

    Example of value

    provider-uri

    The URI of the OIDC Provider

    https://okta.myorg.com

    id-token-user-property

    The field of the ID Token that indicates the Conjur username.

    Recommended: To avoid duplication, this property should use a field that holds unique values, for example, username or userID

    Note: The user can be defined in the root policy only,

    preferred_username

    For more details, see Setting variable values.

  4. Enable Conjur users to authenticate using the OIDC Authenticator

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

       
      - !grant
        role: !group conjur/authn-oidc/<service-id>/users
      members: - !group <user-group> - !user <user>

      Provide the following:

      service-id The service ID of your OIDC Provider.
      user-groups/user

      One or more user groups and/or users who must authenticate using OIDC.

    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
       
      conjur policy load root 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 Okta OIDC Provider endpoint conjur/authn-oidc/okta, allowlist authn-oidc/okta.

  6. Check the authenticator status

    Check that the authenticator is configured correctly. For details, see Configure the status webservice.

Application authentication flow

The following flow represents how an application authenticates with Conjur using the OIDC Authenticator. This flow assumes that the application already has an ID Token.

 

This flow relates to applications and services alike.

For the OIDC authentication flow for the Conjur UI, see.

  1. The application sends an authentication request to Conjur using the provided Base64-encoded ID Token. See OIDC Authenticator.

  2. After receiving the ID Token authentication request, Conjur does the following:

    1. Validates the ID Token against the OIDC Provider.

    2. Extracts the Conjur username from the ID Token, using the value in the id-token-user-property variable, and looks for a user or host with that username.

    3. Validates that the user with the above username exists in the root policy and has permission to authenticate using the OIDC Authenticator.

    4. Audits the authentication request.

    5. Returns an access token to the application.

  3. The application can retrieve the permitted secrets it needs using the access token.

OIDC Authenticator for Conjur UI authentication

How does it work?

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

  2. The user visits the Conjur UI sign in page and selects an available OIDC authentication method.

  3. Conjur redirects the user to the OIDC provider's sign-in page.

  4. After the user successfully signs in, the OIDC application redirects the user to the Conjur UI 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.

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

For more information, see OpenID Connect (OIDC) Authenticator.

Configure the OIDC Authenticator to enable sign in to the Conjur UI

  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 an Okta OIDC Provider, the service ID can be okta.

    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/okta
        body:
        - !webservice
      
        - !variable provider-uri
        - !variable client-id
        - !variable client-secret
      
        # URI of Conjur instance
        - !variable redirect_uri
      
        # Defines the JWT claim to use as the Conjur identifier
        - !variable claim-mapping
      
        # Nonce and State are random strings generated to supply an
        # additional layer of security. These values should be generated when the
        # authenticator is created.											
        - !variable state
        - !variable nonce
      
        - !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
    2. Save the policy as a .yml file using the following file naming convention: 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

    state

    A randomly generated string used for request verification. This should be set by the Conjur administrator during setup.

    nonce

    A randomly generated string used for request verification. This should be set by the Conjur administrator during setup.

    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.

    claim-mapping

    List of space-delimited claims to which the client requests access from the OIDC provider.

    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/okta/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
       
      conjur policy load root 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 Okta OIDC Provider endpoint conjur/authn-oidc/okta, allowlist authn-oidc/okta.

  6. Check the authenticator status

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

Conjur UI authentication flow

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

  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 and makes a request to Conjur with the retrieved code and state values.

    2. Conjur verifies the retrieved code and state and performs back-channel authentication with the OIDC provider.

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

Conjur authentication

To understand how Conjur authenticates users and hosts to retrieve secrets, see Authentication.

Security considerations

When working with Conjur-OIDC authentication, consider the following:

  • Do not set a single OIDC Identity Provider Issuer (often referred to as the Entity ID or "Issuer") to serve multiple tenants (two or more) as the tenants end up sharing the same signing keys, and then there is no real native ability for the Issuer to distinguish between tenants. As an alternative, we highly recommend running a single issuer per tenant to avoid such multi-tenancy security risk.

  • When you add or remove a user from your OIDC identity provider you must respectively add or remove the user in Conjur.

Troubleshooting OIDC authentication

OIDC Authenticator REST API

Once the OIDC Authenticator is configured, you can send an authentication request.

For more information, see OIDC Authenticator.

Limitations

  • Only users that are defined in the root policy can authenticate using the OIDC Authenticator.
  • The admin user is not able to authenticate using the OIDC Authenticator.

  • The OIDC Authenticator cannot be used in the Conjur CLI.
  • The OIDC Authenticator for Conjur UI currently supports only Okta as an OIDC provider.
  • When using Okta for MFA with an OIDC Authenticator, Conjur supports only the following claims:
    • email
    • preferred_username
  • The OIDC Authenticator for Conjur UI use case does not support custom claims.