Configure OAuth
The setup of your OAuth/OpenID (OIDC) Provider(s) to enable Single Sign-On is done in the Configure OAuth tab. We will get to the details of the steps to configure this tab and the meaning of different options on this page.
First, you have to select an application you want to configure as an OAuth/OpenID (OIDC) Provider from the Select Application dropdown that lists all the supported OAuth/OpenID (OIDC) Providers along with ‘Custom OpenID’ and ‘Custom App’ as options.
For simplicity, we are going to use ‘provider’ instead of ‘OAuth/OpenID (OIDC) Provider’ in this document.
We support the following OAuth and OpenID providers and below are the links to their guides.
OAuth Apps
| Azure AD | Discord | Github | |
| Github Enterprise | Gitlab | Google Apps | Meetup |
| miniOrange | Slack | Salesforce | Gluu Server |
| Custom OAuth App |
OpenID Apps
| ADFS | AWS Cognito | Azure B2C | Keycloak |
| Okta | Custom OpenID App |
If you select any one of the default applications that are supported, the endpoints are already known. So you just need to fill in the application credentials along with some basic information while configuring the app. But if the provider that you are looking for is not present in the ‘Select Application’ list then you can select the option ‘Custom OpenID’ or ‘Custom App’ and configure that provider. Here you need to manually fill all the endpoints.
We provide step by step setup guides for all the supported default apps. You can see the setup guides by clicking ‘View Setup Guide’. The setup guides contain all the steps to create the application on the selected provider and steps to configure the app on the Atlassian application.
In OAuth/OIDC terminology, a client application is an actor that wants to access the protected resource on behalf of the resource owner (user) and with its authorization.
In order to request access to information of users on the provider, the client application must first register with the provider. After successfully creating the application on the provider, you will get all the information to configure the app. The information received from the application on provider can be filled in the respective fields discussed in the later section.
At registration, the client application is assigned a client ID and a client secret (password). The client ID and secret are unique to the client application on that provider. If a client application registers with multiple providers (e.g. Facebook, Okta and Google), each provider will issue its own unique client ID to the client application.
Whenever the Client requests access to information, the client application needs to authenticate itself by sending the client ID and the client secret to the Provider.
General Settings
Callback URL
The Callback URL is used to configure the Authorized Callback URL/Redirect URI field in the provider application. This tells the server where to send the user after authentication with the appropriate tokens. This is the URL where the provider sends the response at an SSO attempt and the app uses the information received from the provider to log in the user and update the user’s information.
Client ID
Client ID is a Public identifier for the Application. In OAuth 2.0 the Client ID is unique for any OAuth Client on the same provider. It is used by providers to identify the client responsible for the OAuth/OpenID (OIDC) request. You can configure Client ID using the App ID of the selected application.
Client Secret
This is a confidential secret key used for authentication. The Client Secret is a secret known only to the Client and the provider. Providers use it to authenticate the application when the application requests to access a user’s account. You can configure Client Secret using the App Secret of the selected application.
Scope
The scope is a mechanism in OAuth and OpenID to limit an application’s access to a user’s account. Each scope grants access to specific information. An application can request one or more scopes, this information is then presented to the user in the consent screen, and the access token issued to the application will be limited to the scopes granted.
For OpenID Providers, the scopes are defined as openid, profile, email, address, and phone and each grant access to that specific information. But for OAuth Providers there are no naming conventions.
Authorize Endpoint
The authorization endpoint is the endpoint on the provider where the user logs in, and grants authorization to the client application. It is used to obtain an authorization code (which is then later exchanged for an access token).
Access Token Endpoint
A request to the token endpoint is used to exchange an authorization code for an access token. The access token is later used to get access to the user information.
Get User info Endpoint
The User Info endpoint can be used to retrieve identity information about a user. The caller sends a valid access token representing the user and depending on the granted scopes, the User Info endpoint returns the user information against based claims.
Fetch Group Endpoint
The groups’ endpoint provides functionality for fetching information about provider user groups. These groups are used to update groups on the local Atlassian application based on your group mapping.
Logout Endpoint
A client uses the logout endpoint to clear the provider-side session and cookies for a web browser. This field is optional. Not all providers support Logout Endpoint, so in that case, you can leave it blank. But if this field is filled in correctly, once you log out of your Atlassian application you will also be logged out of the respective provider.
Provider Specific Settings
Tenant Id
This field is for Azure AD OAuth Provider. It is a mandatory field. In Azure Active Directory, a tenant is an instance of the Azure AD service. It represents an organization within Azure Active Directory. Applications are created inside a tenant. The tenant ID identifies which Azure AD/Azure B2C instance the application sits under, so Azure knows where to look when you request things using that application ID. It is used to generate Authorize Endpoint
(https://login.microsoftonline.com/{tenant_id}/oauth2/authorize) and Access Token Endpoint
(https://login.microsoftonline.com/{tenant_id}/oauth2/token) for Azure AD and Azure B2C.
Host Name
This field is for Keycloak OpenID Provider. It is a mandatory field. The hostname is the name of the host where the Keycloak is running. The hostname represents the network or system used to deliver a user to a certain address or location. It is used to generate Authorize Endpoint ({host_name}/auth/realms/{realm_name}/tokens/login) and Access Token Endpoint
({host_name}/auth/realms/{realm_name}/tokens/access/codes) for Keycloak.
Realm Name
This field is for Keycloak OpenID Provider. It is a mandatory field. A realm, in Keycloak, manages a set of users, credentials, roles, and groups. A user belongs to and logs into a realm. So server authentication service verifies user identity by checking the realm name. The realms are isolated from one another and can only manage and authenticate the users that they control. Here, the realm name is used to generate Authorize Endpoint
({host_name}/auth/realms/{realm_name}/tokens/login) and Access Token Endpoint
({host_name}/auth/realms/{realm_name}/tokens/access/codes) for Keycloak.
Domain Name
A domain name represents the URL on which the application is running. Many applications have a feature to customize the domain URL and run the application on a different URL. Here, the configured domain name is used to generate Authorize Endpoint and Access Token Endpoint for ADFS, AWS Cognito, Okta and Salesforce.
Advanced Settings
Public Key
A public key is a part of asymmetric cryptography. It is used to encrypt data and decrypt the signed data. Here you can fill this field with a public key provided by your OpenID (OIDC) Provider. The OpenID (OIDC) Providers send all the tokens by digitally signing them. So the public key is used to decrypt the signed tokens. The public key is used to confirm the identity of the OpenID (OIDC) Provider and to confirm that the token that has been received is unchanged.
Use State Parameter
The state parameter is used to protect against CSRF attack. The way to prevent CSRF in OAuth is to include a unique and non-guessable value in the authorization request that the client can verify in the response but that an attacker could not know. This unique and non-guessable value is the State Parameter. For some providers, sending this field in the request is optional but some providers don’t approve the request if a state parameter is not included. For the OpenID Providers supported by the add-on, this field is enabled by default.
Use ACR Value Parameter
The ACR value parameter is used to request OpenID (OIDC) Provider to send additional information, which will be needed to determine the Level of Assurance of the user authentication.
Add Custom Parameters
It is used to add extra parameters which will be included in the authentication request.
For example :
Nonce
Nonce is a string value used to verify if a response is coming back from the same server to which the request had been sent. It associates a Client session with an ID Token, and to prevent replay attacks. A random nonce value is sent in the authentication request. This value is passed unmodified from the authentication request to the ID Token. If present in the ID Token, clients must verify that the nonce Claim Value is equal to the value of the nonce parameter sent in the authentication request. If present in the authentication request, authorization servers must include a nonce Claim in the ID Token with the claim value being the nonce value sent in the Authentication Request. Authorization Servers should perform no other processing on nonce values used. The nonce value is a case sensitive string