OpenID Connect Authentication¶

Warning

Current support is experimental and may not cater for all possible configurations or environments.

Canopy supports the Authentication Code Grant flow of OpenID Connect (OIDC) as specified in the OpenID Connect core v1.0 specification (https://openid.net/specs/openid-connect-core-1_0.html).

and the Client Credentials Grant flow as defined in Oauth 2.0 where access tokens are JWTs with the required claims. (https://tools.ietf.org/html/rfc6749#section-1.3.4)

This allows both users and other software to be granted access to Canopy via an OpenID Provider.

User provisioning is enabled by default and claims are mapped to user attribute will result in those attributes being updated.

Important Information¶

The Authentication Code Grant flow can only be used to create a normal cookie based session at this stage and token refreshing is not available.

As such the session timeout should be aligned with the access token lifetime.

Client Credential Grant flow can be used by other software that needs to integrate with Canopy. The access tokens presented by such software must be valid JWTs with all the required claims.

Warning

The email attribute (via a claim mapping) is required for both flows.

Gloassary¶

Word	Description
OIDC	OpenID Connect
OP	OpenID Provider
Role
Claim
Attribute

Basic Configuration¶

Each OpenID Connect provider will require a slightly different configuration but the following entries will often be required.

All the required configuration is done in /etc/canopy/canopy.ini and a restart of services is required for any change to take effect.

Required settings (customise values as required):

OIDC_ENABLE=true
OIDC_OP_AUTHORIZATION_ENDPOINT=https://OP_HOST/adfs/oauth2/authorize/
OIDC_OP_TOKEN_ENDPOINT=https://OP_HOST/adfs/oauth2/token/
OIDC_OP_USER_ENDPOINT=https://OP_HOST/adfs/userinfo # only required when OIDC_FETCH_USERINFO=true
OIDC_RP_CLIENT_ID=your_client_id
OIDC_RP_CLIENT_SECRET=your_client_secret or OIDC_RP_CLIENT_ASSERTION_PEM=/path/to/cert.pem
OIDC_ATTRIBUTE_MAPPING=name=unique_name,email=email
OIDC_OP_JWKS_ENDPOINT=https://ADFS_HOST/adfs/discovery/keys # By default RS256 is used

Settings that are often required:

OIDC_FETCH_USERINFO=false # When claims are sent via id_token/access_token
OIDC_RP_SIGN_ALGO=RS256 # ADFS
OIDC_SSO_NAME=Our SSO
SSO_USER_ROLE_MAPPING=Analysts=analysts

During initial configuration it would also be usefull to increase the log level related to OIDC configuration:

LOG_LEVEL_OIDC=DEBUG

Warning

This setting may log sensitive information and should not be used in production except to debug specific issues for a limited time period.

Claim/Attribute Mapping¶

The OIDC_ATTRIBUTE_MAPPING controls how claims in tokens are mapped to user attributes. Its value is a comma delimited list of attribute / claim pairs.

OIDC_ATTRIBUTE_MAPPING=name=unique_name,email=email

maps the unique_name claim to the user attribute name and the email claim to the email attribute.

Only mapped claims are evaluated and at least the email attribute must be mapped to a claim that is the user’s email address.

Role assignment¶

There are two ways user roles can be assigned via claims in tokens:

List claim that contains the complete role list
Claim per role

Both approaches form part of the OIDC_ATTRIBUTE_MAPPING setting and can be used in combination (must be in the above order as set_role overrides any role mapping before it).

List claim¶

User roles can be sent via a list claim, the user’s roles will be reset to this list. If the complete list of user roles cannot be sent via a single list claim then per role claims will be required, possibly in addition to this.

The list roles attribute needs to be mapped to the set_roles field.

OIDC_ATTRIBUTE_MAP=name=unique_name,email=email,set_roles=groups

in the above example the groups claim is mapped to the set_role attribute.

Role name translation¶

Since the role names may not always match what Canopy expects, one can translate role names being sent via a list attribute using the SSO_USER_ROLE_MAPPING setting.

The mapping is a comma delimited list of OP Role Name = Canopy Role Name

SSO_USER_ROLE_MAPPING=OPRoleName=canopy_role_name1, OPRoleName2=canopy_role_name2

This setting will apply role translation to all SSO methods.

Supported Roles¶

All builtin and custom roles are supported, the builtin list of roles is:

admin
technical_managers
senior_analysts
analysts
schedulers
sales_managers
account_managers
pr_reviewers
qa_reviewers

For custom roles their name will be used which is case sensitive.

Claim per role¶

Assigning roles based on claims is optional and not all flags need to be mapped. Unmapped flags can be managed via the Canopy admin interface. The attribute value should be any string value to signify membership, except for the following strings, which denote the removal of the role: ‘’ (Empty string), ‘no’, ‘false’ and ‘0’.

If the attribute is missing then no adjustment will occur.

Role fields currently supported:

is_admin
is_technical_managers
is_senior_analysts
is_analysts
is_schedulers
is_sales_managers
is_account_managers
is_custom_pr_reviewers
is_custom_qa_reviewers

OIDC_ATTRIBUTE_MAP=email=email, name=name, is_admin=oidc_admin_claim

if per attribute role mappings are in use with list claim role mapping then the role flags should be after the set_roles mapping.

OIDC_ATTRIBUTE_MAP=email=email, name=name, set_roles=roles_claim, is_admin=admin_claim

Note

Per role claims do not support custom roles.

How to configure Windows ADFS 2016¶

Step 1¶

From the ADFS Management console, in the Application Groups section, create a new Application Group of type*Server Application accessing a web API*.

Step 2¶

Add the Canopy callback URL, it is https://CANOPY_HOST/oidc/callback/ Copy the generated Client Identified, it is your OIDC_RP_CLIENT_ID

Step 3¶

Generate a shared secret and copy it also, it is your OIDC_RP_CLIENT_SECRET

Step 4¶

For the Web API identifier, please use the Client Identifier from step 1.

Step 5¶

Select who should be allowed to authenticate.

Step 6¶

Ensure the openid and allatclaims scopes are selected.

Step 7¶

Review the summary, ensure that the identifiers are the same and that the callback URL is correct.

Step 8¶

After completion of the Add Application Group Wizard, double click on the Web API and goto the Issuance Transform Rules and add a rule to send LDAP attributes as claims.

Configure atleast an email claim.

Debugging¶

If your ADFS present any kind of error you can consult the Event Viewer to see why.

Example Windows ADFS 2016 Configuration¶

OIDC_ENABLE=true
OIDC_RP_SCOPES=openid email profile allatclaims
OIDC_RESPONSE_MODE=form_post
OIDC_RP_CLIENT_ID=your_client_id
OIDC_RP_CLIENT_SECRET=your_client_secret
OIDC_OP_AUTHORIZATION_ENDPOINT=https://ADFS_HOST/adfs/oauth2/authorize/
OIDC_OP_TOKEN_ENDPOINT=https://ADFS_HOST/adfs/oauth2/token/
OIDC_OP_JWKS_ENDPOINT=https://ADFS_HOST/adfs/discovery/keys
OIDC_FETCH_USERINFO=false

OIDC_ATTRIBUTE_MAPPING=name=unique_name,email=email,set_roles=groups
SSO_USER_ROLE_MAPPING=ADFSGroup1=CanopyRole1

Example Okta Configuration¶

OIDC_ENABLE=true
OIDC_RP_CLIENT_ID=your_client_id
OIDC_RP_CLIENT_SECRET=your_client_secret
OIDC_OP_AUTHORIZATION_ENDPOINT=https://YOUR_BASE_URL.okta.com/oauth2/default/v1/authorize
OIDC_OP_TOKEN_ENDPOINT=https://YOUR_BASE_URL.okta.com/oauth2/default/v1/token
OIDC_OP_USER_ENDPOINT=https://YOUR_BASE_URL_okta.com/oauth2/default/v1/userinfo
OIDC_OP_JWKS_ENDPOINT=https://YOUR_BASE_URL.okta.com/oauth2/default/v1/keys
OIDC_FETCH_USERINFO=true

OIDC_ATTRIBUTE_MAPPING=name=name,email=email,set_roles=groups
SSO_USER_ROLE_MAPPING=OKTAGROUP1=CanopyRole1

Configuration Options¶

Settings	Description	Default
OIDC_ENABLE	Enable OIDC authentication	false
OIDC_CREATE_USER	Create non-existent users	true
OIDC_RP_CLIENT_ID	Client Identifier of Relying Party
OIDC_RP_CLIENT_SECRET	Client Secret of Relying Party. This or OIDC_RP_CLIENT_ASSERTION_PEM must be set.
OIDC_RP_CLIENT_ASSERTION_PEM	Client certificate path/filename for `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` client assertion. PEM format contaning atleast the client certificate and private key. This file will be re-read for each SSO attempt. Cannot be used in conjunction with OIDC_RP_CLIENT_SECRET
OIDC_OP_AUTHORIZATION_ENDPOINT	URL of OIDC authorization endpoint
OIDC_OP_TOKEN_ENDPOINT	URL of OIDC token endpoint
OIDC_OP_USER_ENDPOINT	URL of OIDC userinfo endpoint
OIDC_OP_JWKS_ENDPOINT	URL of OIDC jwks endpoint
OIDC_RP_SIGN_ALGO	Algorithm with witch tokens are signed: RS256 or HS256	RS256
OIDC_RP_IDP_SIGN_KEY	Signing key for HS256 algorithm
OIDC_VERIFY_SSL	Verify TLS certification during back channel communication with OP	true
OIDC_TIMEOUT	Timeout for back channel communication with OP
OIDC_PROXY	Proxy to use for back channel communication with OP
OIDC_RP_SCOPES	Scopes to request. openid is required.	openid email profile
OIDC_SSO_NAME	Name to display for SSO login on login screens	OpenID Connect
OIDC_FETCH_USERINFO	Should userinfo endpoint be queried for additional claims, required for opaque access tokens.	false
OIDC_MERGE_ALL_CLAIMS	Should claims contained in all JWT tokens be merged	true
OIDC_VERIFY_ACCESS_TOKEN	Should access token be verified (As JWT or via userinfo endpoint)	true
OIDC_JWKS_CACHE_TIMEOUT	Timeout in seconds of JWKS key cache	3600
OIDC_RESPONSE_MODE	Response type used by OP when calling Canopy’s callback URL.
OIDC_ATTRIBUTE_MAPPING	Mapping of claims to user attributes	email=email

Debugging¶

All the required information to debug OIDC interaction will be logged under the Canopy process when the LOG_LEVEL_OIDC is set to DEBUG.

In /etc/canopy/canopy.ini set:

LOG_LEVEL_OIDC=DEBUG

restart Canopy service and attempt a login.

Consult Canopy logs for information regarding the login process, claim to attribute mapping and role mapping.

journalctl -u canopy -e