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 your provider page that lists all the supported OAuth/OpenID (OIDC) Providers along with ‘Custom OpenID App’ and ‘Custom OAuth App’.
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 your Provider’ list then you can select the option ‘Custom OpenID App’ or ‘Custom OAuth 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’ button. 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 the 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 for the 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 group's 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 OAuth 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 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, realm manages a set of users, credentials, roles, and groups. A user belongs to and logs into a realm. 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. Here, the configured domain name is used to generate Authorize Endpoint and Access Token Endpoint for ADFS, AWS Cognito, Okta and Salesforce.