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 Conjur 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 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 OIDC authentication flow.

Conjur authentication

To understand how Conjur 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 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.

    • 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 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, set the CONJUR_AUTHENTICATORS variable as an environment variable:

     
    export CONJUR_AUTHENTICATORS=<authenticator-names>
     

    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.

    For more information about enabling authenticators in Conjur, see Configure Authentication.

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

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.