OpenID Connect (OIDC) Authenticator

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.

CyberArk's OIDC Authenticator leverages the identity layer provided by OIDC to allow applications to authenticate with Dynamic Access Provider (DAP) and retrieve secrets needed for connecting to services such as a database.

 

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

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 DAP, it authenticates with DAP using the ID Token it received from the OIDC Provider.

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

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

For more information, see OIDC authentication flow.

DAP authentication

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

Configure the OIDC Authenticator

This section describes how to set up the OIDC Authenticator.

  1. Prerequisite: Define DAP 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.

    • Variables can be created and permitted to users using policy.
    • Users can be created 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 DAP 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 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 DAP 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 DAP 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 root authn-oidc-<service-id>-users.yml
  5. Enable the OIDC Authenticator

    In this step you enable the OIDC Authenticator on every DAP Server you are authenticating to with OIDC.

    To enable the OIDC Authenticator, set the CONJUR_AUTHENTICATORS variable as an environment variable:

    1. Edit the file located in the DAP Server container in /opt/conjur/etc/conjur.conf and add the following line:

       
      CONJUR_AUTHENTICATORS=<authenticator-names>
    2. Restart the services:

       
      sv restart conjur
     

    The value for this variable should be identical to the name given to the policy ID above, excluding the conjur/ prefix.

    For example, for an Okta OIDC Provider:

     
    CONJUR_AUTHENTICATORS=authn-oidc/okta

    For more information about enabling authenticators in DAP, see Allowlist the Authenticators.

  6. Check the authenticator status

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

OIDC authentication flow

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

 

This flow relates to applications and services alike.

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

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

    1. Validates the ID Token against the OIDC Provider.

    2. Extracts the DAP 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.

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.