OIDC Integration with CalNet

Use the resources below to get your application up and running with OIDC authentication.

Step 1 - OIDC Implementation Guidelines

The following guidelines should be considered to ensure your OIDC integration will work with the CalNet Central Authentication Service.

Supported OIDC Flows

Authorization Code Flow with Proof Key for Code Exchange (PKCE) is the only supported OIDC flow.

During authentication, mobile and native applications can use the Authorization Code Flow, but they require additional security. Additionally, single-page apps have special challenges. To mitigate these, OAuth 2.0 provides a version of the Authorization Code Flow which makes use of a Proof Key for Code Exchange (PKCE).  We do not support other flow types (e.g. implicit, hybrid, etc).

Endpoints

OIDC Discovery

The OpenID Connect discovery endpoint is a URL where OpenID Connect providers make their configuration information (metadata) available in a standardized format. This endpoint helps clients dynamically discover information about the OpenID provider, such as its supported authentication methods, endpoints, and public keys.  Many client libraries can use this endpoint to discover all other settings.

Test: https://auth-test.berkeley.edu/cas/oidc/.well-known

Production: https://auth.berkeley.edu/cas/oidc/.well-known

All Endpoints

If your application requires individual endpoints be configured then the following table lists the endpoints available for both https://auth.berkeley.edu and https://auth-test.berkeley.edu

Endpoint

Description

/cas/oidc

Issuer

/cas/oidc/oidcAuthorize

Authorization.  Used by the app to obtain authorization from the end-user.

/cas/oidc/oidcAccessToken

Token.  Used by the app to exchange an authorization code or refresh token for an access token, ID token, and optionally a refresh token.

/cas/oidc/oidcProfile

UserInfo. Used by the app to obtain profile information about the authenticated user. 

/cas/oidc/jwks

JWKS. Provides the public keys used to verify the signature on the ID tokens.

/cas/oidc/.well-known/openid-configuration

Discovery. Provides metadata about the OpenID provider, including URLs for the other endpoints, supported claims, etc.

/cas/oidc/oidcLogout

End Session. Allows the app to log the user out from the OP.

/cas/oidc/revoke

Revocation. Allows the app to inform the OP that a previously obtained token is no longer needed and should be revoked.

Client Identification

In OpenID Connect, the client_id and client_secret are essential for the security and proper functioning of the authentication and authorization process.  CalNet will supply both of these values after you submit an SSO Service Request (Step 3).

client_id: Uniquely identifies the client application to the OpenID Connect provider. This allows the provider to recognize which application is making the authentication or authorization request.

client_secret: Is used to authenticate the client application to the OpenID Connect provider.  Helps prevent unauthorized applications from impersonating the client.

Important: Per theMinimum Security Standards for Networked Devices (MSSND), secrets stored on servers must be made resistant to offline attacks according toNIST guidelines NIST SP 800-63B, Sec. 5.1.1.2.  In addition, the requirements of theUC Encryption Key and Certificate Management Standard are applicable to the OIDC client_secret credentials.

Supported Scopes and Claims

OpenID Connect (OIDC) scopes are used by an application during authentication to authorize access to a user's details, like name, email address, group membership. Each scope returns a set of user attributes, which are called claims. The scopes an application should request depend on which user attributes the application needs. Once the user authorizes the requested scopes, the claims are returned in an ID Token and are also available through the /userinfo endpoint.

The basic (and required) scope for OIDC is openid, which indicates that an application intends to use the OIDC protocol to verify a user's identity. Beyond that, an application can ask for additional scopes by listing the requested scope names in the scope parameter, separated by spaces.

We support the following scopes, note that some of these are considered private and require special approval.  For a full listing of claims and the associated source attribute see supported OIDC Scopes and Claims.

Standard Claims

Scope

Claims

openid

Required.  Returns the sub claim, which uniquely identifies the user. In an ID Token, iss, aud, exp, iat, and at_hash claims will also be present. To learn more about the ID Token claims, read ID Token Structure.

profile

Returns claims that represent basic profile information, including name, family_name, given_name,preferred_username

email

Private. Returns the email claim, which contains the user's email address.

Custom Claims

Scope

Claims

berkeley_edu_default

Commonly used attributes used for authorization decisions including uid, groups, and affiliations

berkeley_edu_dept_number

department_number

berkeley_edu_employee_id

employee_id

berkeley_edu_cs_id

Campus Solutions, cs_id

berkeley_edu_student_id

student_id

berkeley_edu_ou

LDAP organizational unit, ou

Step 2 - SocReg Registration

  1. Please be sure the system which hosts your application has been registered with the Socreg Application. Refer to the campus Departmental Security Contact Policy for more details on this requirement. 

  2. If your application provides access to restricted data, you are highly encouraged to participate in the Web Application Security Testing program.

Step 3 - SSO Service Request

All SSO services are required to register, and provide contact information.  All services must have a UCB Faculty/Staff contact/sponsor.

  1. Please read the CAS Terms of Service

  2. Review and understand the SSO Authorization page.  The intent of CAS authorizations is to ensure that all registered services are providing some level of authorization, and providing a CalNet default authorization if they are not.

  3. Fill out the SSO Registration Form in ServiceNow (login is required).  You can also choose to modify or delete an existing service by following that link.   All services must have a UCB Faculty/Staff contact/sponsor.