- 28 Feb 2024
- 6 Minutes to read
- Print
- DarkLight
Understanding OpenID Connect Integration with Agile.Now
- Updated on 28 Feb 2024
- 6 Minutes to read
- Print
- DarkLight
Agile.Now is committed to providing secure and robust integration capabilities for modern software development and project management tools. In the realm of user authentication and identity services, Agile.Now supports the OpenID Connect (OIDC) standard, an identity layer on top of the OAuth 2.0 protocol.
Agile.Now and OpenID Connect Standards
Agile.Now leverages OpenID Connect to authenticate users and provide secure access to applications. This standard enables clients to verify the identity of an end-user based on the authentication performed by an Authorization Server and to obtain basic profile information about the end-user in an interoperable and REST-like manner.
Key Components in Agile.Now's OpenID Connect Implementation
Id_token: A security token that contains Claims (user information) about the authenticated user.
.well-known/openid-configuration: An important part of the OpenID Connect discovery process, this URI (Uniform Resource Identifier) allows clients to retrieve metadata about the OpenID Provider. In Agile.Now, it's accessible at:
https://<server url>/oauth/rest/v2/default/.well-known/openid-configuration
.well-known/jwks: JSON Web Key Set (JWKS) is a set of keys containing the public keys used to verify any JSON Web Token (JWT) issued by the authorization server. Agile.Now exposes this at:
https://<server url>/oauth/rest/v2/default/.well-known/jwks-keys
If your environment is not configured to use the Agile.Now Workspace Hub, the OpenID configuration will default to the main tenant settings. Please ensure you are aware of the proper OpenID Connect setup for your environment to maintain system security and functionality.
Supported Standards and Features
Agile.Now's OpenID Connect implementation provides a variety of features and standards:
- Issuer:
https://<server url>/
- Authorization Endpoint:
https://<server url>/oauth/authorize
- Token Endpoint:
https://<server url>/oauth/rest/v2/token
- End Session Endpoint:
https://<server url>/oauth/logout
- User Info Endpoint:
https://<server url>/oauth/rest/v2/me/userinfo
- JWKS URI:
https://<server url>/oauth/rest/v2/default/.well-known/jwks-keys
- Supported Scopes:
openid
,profile
,email
,phone
,roles
- Supported Response Types:
code
,token
,id_token
, and combinations thereof - Supported Response Modes:
query
,fragment
- Supported Subject Types:
public
- Supported ID Token Signing Algorithms:
HS256
,RS256
- Supported Token Endpoint Authentication Methods:
client_secret_basic
,client_secret_post
- Supported Claims: (Table provided below)
- HTTP Logout Supported:
true
- Supported Token Endpoint Authentication Signing Algorithms:
HS256
,RS256
Supported Claims
Below is a table of the user information claims supported by Agile.Now's OpenID Connect implementation:
Name | Description |
---|---|
name | Full name of the user. |
given_name | Given name(s) or first name(s) of the user. |
family_name | Surname(s) or last name(s) of the user. |
email | Preferred email address of the user. |
preferred_username | Shorthand name by which the user wishes to be referred to. |
oid | Object Identifier - an identifier for the user at the issuer. The identifier for a user or an object across applications. This identifier remains constant across all applications, even if the user's information, such as their username or email, changes. |
roles | Roles assigned to the user. |
tid | Tenant Identifier - an identifier for the tenant that the user is a part of. For applications serving multiple organizations, the tid claim identifies the specific tenant (organization) associated with the user. |
phone_number | Preferred telephone number of the user. |
amr | Authentication Methods References - an array of strings that indicates the methods used in auth. |
scp | Scopes - an array of strings representing the scope of access. |
ipaddr | IP Address - the IP address of the user when they authenticated. |
locale | Locale of the user, typically an ISO 639-1 language code and an ISO 3166-1 country code. |
exp | Expiration time on or after which the ID Token MUST NOT be accepted. |
auth_time | Time when the authentication occurred. |
iat | Issued At - time at which the JWT was issued. |
iss | Issuer Identifier for the Issuer of the response. |
sub | Subject Identifier - a locally unique and never reassigned identifier for the user. |
aud | Audience(s) that this ID Token is intended for. The client ID of the OAuth client that requested the ID token. |
azp | The Authorized Party claim in an ID token is used in OpenID Connect and OAuth 2.0 protocols. The client ID of the OAuth client that requested the ID token. |
By adhering to these standards, Agile.Now ensures a secure and seamless integration experience for users, allowing them to authenticate and access applications with confidence and ease.
Supported Standards and Features in Agile.Now's OpenID Connect Implementation
Agile.Now's integration with OpenID Connect (OIDC) is comprehensive, supporting a wide array of standards and features that enhance security and provide flexibility in authentication and identity management. Below, we delve into the details of each supported feature:
Issuer
The issuer is a URL that uniquely identifies the authorization server that issued the token. For Agile.Now, this is https://<server url>/
.
Authorization Endpoint
This URL is used to initiate the authorization flow. Clients send requests to this endpoint, and users authenticate and grant consent here. For Agile.Now, it's https://<server url>/oauth/authorize
.
Token Endpoint
Clients obtain tokens from this endpoint post-authentication. It supports various grant types including authorization code, refresh token, etc. Agile.Now has it at https://<server url>/oauth/rest/v2/token
.
End Session Endpoint
Also known as the logout endpoint, this URL allows users to end their session. Agile.Now provides this functionality at https://<server url>/oauth/logout
.
User Info Endpoint
This endpoint provides information about the user. Once authenticated, clients can request user details such as name, email, and other profile information. Agile.Now's User Info Endpoint is accessible at https://<server url>/oauth/rest/v2/me/userinfo
.
JWKS URI
The JSON Web Key Set (JWKS) endpoint contains public keys that clients use to verify the signature of tokens. Agile.Now exposes this at https://<server url>/oauth/rest/v2/default/.well-known/jwks-keys
.
Supported Scopes
Scopes define the level of access that the application is requesting from the user. Agile.Now supports scopes like openid
, profile
, email
, etc., enabling fine-grained access control.
Scope | Claims Description |
---|---|
openid | (required) Returns the sub claim, which uniquely identifies the user. In an ID Token, tid , amr , ipaddr , locale , exp ,auth_time , iat , iss , aud and azp 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 , and preferred_username . |
email | Returns the email claim, which contains the user's email address.. |
roles | Roles assigned to the user. |
phone | Preferred telephone number of the user. |
Supported Response Types
Agile.Now supports various response types including code
(Authorization Code Flow), token
(Implicit Flow), and id_token
(for obtaining an ID Token directly), among others. This versatility allows developers to choose the flow that best suits their application's needs.
Supported Response Modes
Response modes dictate how tokens are returned to the client. Agile.Now supports query
and fragment
, providing flexibility in how clients receive the authorization response.
Supported Subject Types
This defines how the subject (user) identifier is generated. Agile.Now uses the public
subject type, where the sub claim is a public identifier for the user, unique across all clients.
Supported ID Token Signing Algorithms
These are the cryptographic algorithms used to sign ID Tokens. Agile.Now supports HS256
(HMAC with SHA-256) and RS256
(RSA signature with SHA-256), ensuring robust security for tokens.
Supported Token Endpoint Authentication Methods
These methods define how the client authenticates to the token endpoint. Agile.Now supports client_secret_basic
and client_secret_post
, allowing clients to authenticate using a client secret sent in the HTTP Authorization header or in the request body.
HTTP Logout Supported
This indicates whether Agile.Now supports HTTP-based logout mechanisms. Agile.Now has this feature enabled, ensuring users can securely end their sessions.
Supported Token Endpoint Authentication Signing Algorithms
This defines the algorithms that the server supports for verifying the client's authentication signature. Agile.Now supports HS256
(HMAC with SHA-256) and RS256
(RSA signature with SHA-256), ensuring robust security for tokens.
Code Challenge Method
The Code Challenge Method is part of the Proof Key for Code Exchange (PKCE) extension to OAuth 2.0. This method enhances the security of the authorization code flow by requiring a code challenge to be sent to the authorization endpoint. Agile.Now supports the following Code Challenge Methods:
plain
: Where the code challenge sent is the same as the code verifier.S256
: Where the code challenge is a Base64 URL-encoded SHA-256 hash of the code verifier. This method is recommended for heightened security.
Code Challenge
The Code Challenge is a transformed version of the code verifier, which is generated by the client and sent to the authorization server. It is used to verify that the same device that initiated the authorization request is exchanging the authorization code for an access token. This process mitigates the risk of an authorization code interception attack. Agile.Now's implementation of the Code Challenge ensures robust security in the authorization code flow.
Conclusion
By implementing these standards and features, Agile.Now ensures that its OIDC integration is robust, flexible, and secure, providing users and developers with a seamless authentication and identity management experience.