OpenID Connect (OIDC) Authenticator
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?
A user logs into an application.
The application uses the OIDC Provider to authenticate the user. For details, see OpenID Connect.
If the user is authenticated, the OIDC Provider sends back an ID Token.
The application sends out the ID Token to other application components or microservices.
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.
Conjur sends an access token to the application component.
The application component uses the access token to retrieve secrets and perform other actions in Conjur.
For more information, see OIDC authentication flow.
To understand how Conjur authenticates users and hosts to retrieve secrets, see Authentication.
This section describes how to set up the OIDC Authenticator.
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
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.
- !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
- Save the policy as a .yml file using the following file naming convention: authn-oidc-<service-id>.yml
Load the policy file into any level below root.
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>
Example of value
The URI of the OIDC Provider
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,
For more details, see Setting variable values.
Enable Conjur users to authenticate using the OIDC Authenticator
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.
Save the policy as a .yml file using the following file naming convention: authn-oidc-<service-id>-users.yml
Load the policy file at root level:
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:
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.
Check the authenticator status
Check that the authenticator is configured correctly. For details, see Authenticator Status Webservice.
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.
The application sends an authentication request to Conjur using the provided Base64-encoded ID Token. See OIDC Authenticator.
After receiving the ID Token authentication request, Conjur does the following:
Validates the ID Token against the OIDC Provider.
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.
Validates that the user with the above username exists in the root policy and has permission to authenticate using the OIDC Authenticator.
Audits the authentication request.
Returns an access token to the application.
The application can retrieve the permitted secrets it needs using the access token.
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
Check the authenticator status using the Authenticator Status API. For details, see Authenticator Status Webservice.
Resolution: Make sure OIDC Provider and Conjur Server time are aligned.
Conjur Server, run the date command:
docker exec <Conjur-container-name> date
Validate that the returned time is aligned to the OIDC Provider in one of the following ways:
- Decode a valid ID Token to extract the time
- Check the time in the OIDC Provider dashboard
Once the OIDC Authenticator is configured, you can send an authentication request.
For more information, see OIDC Authenticator.
- 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.