Project: CyberArk Conjur (Provisioning / Key Management)
File: identity_support.md

- - - - - - - - - - - - <small><i><a href='http://ecotrust-canada.github.io/markdown-toc/'>Table of contents generated with markdown-toc</a></i></small> Given the recent upgrades to the V2 OIDC Authenticator, and that the only currently supported OIDC provider is Okta, we should upgrade the V2 OIDC Authenticator to support CyberArk Identity. See existing %20Authenticator%7C_2) and for AuthnOIDC V2. Conjur's AuthnOIDC V2 implementation is intended to be, for the most part, provider agnostic. This is in large part because the endpoints of the OIDC API that Conjur interacts with are well-defined across the various OIDC specifications. This solution will mostly cover: API differences between Okta and Identity Required testing updates across concerned projects Required documentation updates In theory, AuthnOIDC V2 should support any OIDC provider that adheres to the OIDC specifications. The following section will examine the Okta and Identity OIDC APIs, and try to determine whether support for one implies support for the other. The following table displays the differences between the API endpoint paths required for Conjur's AuthnOIDC V2 flow. | Endpoint | Okta | Identity | |-||-| | Metadata | `/.well-known/openid-configuration` | `/${app_id}/.well-known/openid-configuration` | | Authz | Parsed from provider metadata | Parsed from provider metadata | | Token | Parsed from provider metadata | Parsed from provider metadata | Given that the Authz and Token endpoints are both parsed from the provider's metadata endpoint, differences in path structure will not matter. As long as the `${app_id}` is included in the path of the provider URI set up during Authenticator configuration, it should propagate to the rest of the API paths. The following table displays the differences between the API endpoint parameters required for Conjur's AuthnOIDC V2 flow. | Endpoint | Okta: Required | Okta: Optional | Identity: Required | Identity: Optional | |-|-|-|--|--| | Metadata | None | None | None | None | | Authz | <ul><li>`clientid`<li>`redirecturi`<li>`responsetype`<li>`scope`<li>`state`</ul> | <ul><li>`codechallenge`<li>`codechallengemethod`<li>`nonce`</ul> | <ul><li>`clientid`<li>`redirecturi`<li>`responsetype`<li>`scope`<li>`state`<li>`appid` (path, given)</ul> | <ul><li>`codechallenge`<li>`codechallenge_method`<li>`nonce`</ul> | | Token | <ul><li>`granttype`<li>`code`<li>`codeverifier`<li>`redirecturi`</ul> | None | <ul><li>`granttype`<li>`code`<li>`codeverifier`<li>`redirecturi`<li>`clientid`<li>`appid` (path, given)</ul> | None | Identity requires the `client_id` parameter on token requests ]. In the current AuthnOIDC implementation, the `clientid` and `clientsecret` credential pair are sent to the OIDC provider (currently Okta) in an Authorization header ]. From Identity's documentation, it is not clear whether an Authorization header containing the `clientid` and `clientsecret` parameters will be accepted as it is by Okta. If the Authz Header is accepted, then no changes are required. If the Authz Header is not accepted, then we could configure the OIDC client to send the required parameters as part of the request body, which is also accepted by

Update: After setting up Conjur UI with an AuthnOIDC V2 instance backed by Identity, this concern does not require any changes to Conjur's OIDC client. The client successfully authenticates with Identity as currently implemented. The user interface for an AuthnOIDC V2 instance representing Identity will be the same as one representing Okta. Depending on the answers to the questions listed in the section, there may be no need to code changes beyond those made to testing. Depending on the answers to the questions listed in the section, there may be no need to code changes beyond testing, and will be backwards compatible. Given that the bulk of the work required to validate support for Identity will be as dev environment and testing updates, the following work can be done in parallel: Enable Identity development across required projects by including Identity in existing development and CI environments. Conjur Conjur UI Conjur CLI Go Add Identity to testing strategy across required projects Conjur. See . Conjur UI. See . Conjur CLI Go. See . The current AuthnOIDC V2 test matrix that validates support for Okta, if repurposed to target Identity, would also validate support for Identity. Validating support for a general OIDC provider. Identity instance available for testing in CI Identity instance available for development environment | Component | Title | Given | When | Then | Comment | ||--|--|-|-|-| | conjur | Happy Path Integration Test | Given an AuthnOIDC V2 instance is properly configured to authenticate with an Identity instance | When a user properly authenticates with AuthnOIDC V2 through Conjur's API | Then the user is authenticated and given a Conjur access token | See | | | Multi-Authenticator, Multi-Provider Environment | Given a Conjur server has been configured with more than one AuthnOIDC V2 instance, and given that those instances each point to a different OIDC provider (e.g. Okta and Identity) | When a user authenticates with one authenticator | Then the other authenticators are unaffected, and can be used as expected | | | | OIDC Client Unit Tests | | | | There are a number of that validate Conjur's . These depend on VCR to playback - these should be supplemented with authentic Identity API calls, so each unit test case can be run against each to validate compatibility. See for an

| | conjur-cli-go | Happy Path Integration Test | Given an AuthnOIDC V2 instance is properly configured to authenticate with an Identity instance | When a user properly authenticates with AuthnOIDC V2 through the Go CLI | Then the user can use the CLI to perform authorized actions, like policy load and secret retrieval. | See | | | Bad Credentials Integration Test | Given an AuthnOIDC V2 instance is properly configured to authenticate with an Identity instance | When a user attempts to authenticate with Identity with invalid credentials | Authentication fails, and the CLI eventually times-out the authentication command | | | conjur-ui | Happy Path Integration Test | Given an AuthnOIDC V2 instance is properly configured to authenticate with an Identity instance | When a user properly authenticates with AuthnOIDC V2 through the UI | Then the user is logged in to the UI | See | | | Bad Credentials Integration Test | Given an AuthnOIDC V2 instance is properly configured to authenticate with an Identity instance | When a user attempts to authenticate with Identity with invalid credentials | Authentication fails, and the user is not redirected to Conjur UI | | %20Authenticator%7C_0) Limitations section lists Okta as the only available provider. This list needs to be updated. There are a lot of points in the documentation where we describe a service or configuration based on Okta, but we could change this to Identity to be internally consistent. An important detail: Identity has a `client_id`, which is defined in the OIDC specification, and an `appid`. These are separate IDs, with `appid` being a path parameter and `clientid` being a query or request body parameter. The `appid` value must be included in the AuthnOIDC V2 config variable `provider-id`. When included, the `app_id` value will propagate to the Authz and Token endpoints through provider metadata retrieval. Given the limited scope of this effort, and given the rigorous consideration of security issues before and during the initial implementation of AuthnOIDC V2, I have not encountered any new security concerns. This solution depends on the Infrastructure team providing a CyberArk Identity instance for development and testing. This is in progress. | Name (ID) | Description | Issued On | ||--|| | | | | See API Differences: Okta vs Identity subsection . Solution designed is approved Test plan is reviewed Acceptance criteria have been met Tests are implemented according to test plan The behaviour is documented in Conjur Open Source and Enterprise Documentation has been validated by a manual UX walkthrough All relevant components are released | Persona | Name | Sign-off | |--||--| | Team leader | John Tuttle (@jtuttle) | | | Product owner | Nitesh Taneja (@niteshtaneja) | | | System architect | Jason Vanderhoof (@jvanderhoof) | | | Security architect | Andy Tinkham (@andytinkham) | | | QA architect | Adam Ouamani (@adamoumani) | |