OpenID Connect (OIDC) Authenticator
CyberArk's OIDC Authenticator leverages the identity layer provided by OIDC to allow applications to authenticate with
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 DAP, it authenticates with DAP using the ID Token it received from the OIDC Provider.
DAP sends an access token to the application component.
The application component uses the access token to retrieve secrets and perform other actions in DAP.
For more information, see OIDC authentication flow.
To understand how DAP authenticates users and hosts to retrieve secrets, see Authentication.
This section describes how to set up the OIDC Authenticator.
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
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.
- !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 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 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,
For more details, see Setting variable values.
Enable DAP 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:
conjur policy load root authn-oidc-<service-id>-users.yml
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:
Edit the file located in the DAP Server container in /opt/conjur/etc/conjur.conf and add the following line:
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:
For more information about enabling authenticators in DAP, see Allowlist the Authenticators.
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 DAP 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 DAP using the provided Base64-encoded ID Token. See OIDC Authenticator.
After receiving the ID Token authentication request, DAP does the following:
Validates the ID Token against the OIDC Provider.
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.
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.
Troubleshooting OIDC authentication
Error code in logs: CONJ00044E - Concurrency limited cache reached before cache initialized
Resolution: Make sure the OIDC Provider URI defined in the authenticator policy (provider-uri) is accessible from the Follower machine.
Log in to DAP with the Conjur CLI and fetch the provider-uri variable
conjur variable value conjur/authn-oidc/keycloak/provider-uri https://keycloak:8443/auth/realms/master
Check the communication from the Follower machine to OIDC provider.
curl -Is https://keycloak:8443/auth/realms/master | head -n 1 HTTP/1.1 200 OK
Rerun authentication requests until the following message is written in the log:
CONJ00021D - Concurrency limited cache updated successfully
Resolution: Make sure OIDC Provider and DAP server time are aligned.
Followercontainer, run the date command:
docker exec <DAP-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.