Single SignOn (SSO) - Azure Active Directory

Rundeck can be configured to use Azure Active Directory authentication by registering a new application in Azure Active Directory and configuring Runbook Automation to use it.

Configuring Azure Active Directory

Azure - Create a new app registration

The first thing to do is create a new application registration in Azure.

Begin by opening Azure Active Directory in a browser
Select "App registrations" on the left
Select "+ New registration" near the top

Enter "PagerDuty Runbook Automation Self-Hosted" for the Name (or any name you like)
Leave the default selection for the Support account types
Select "Web" for the Redirect URI type
Enter "https://<paop.company.com>/login/oauth2/code/azure" for the Redirect URI
Note: This URL should be your Runbook Automation URL
Select "Register" at the bottom

Azure - Add the required application permissions

Next, add the required permissions in Azure.

Select "API permissions" on the left
Select "+ Add a permission"
Select "Microsoft Graph" as the permission type
Select "Delegated permissions"
Select "email" to enable the permission
Select "openid" to enable the permission
Select "profile" to enable the permission
Select "Add permission" at the bottom

Select "API permissions" on the left
Select "+ Add a permission"
Select "Microsoft Graph" as the permission type
Select "Application permissions"
Enter "Directory.Read.All" in the search box
Select "Directory" to expand it
Select "Directory.Read.All" under Directory to enable the permission
Select "Add permission" at the bottom

Azure - Create the Application Secret

Next, create an application secret (ID & password) that will be used in the Rundeck configuration. Note, if you lose the secret value/password, you can delete the existing secret and create a new one.

Select "Certificates & secrets" on the left
Select "+ New client secret"
Enter "Runbook Automation" for the Description (or any name you choice)
Select "Add" at the bottom

Copy the Value and store it someplace. You will use it as the clientSecret (password) when configuring Rundeck. (Hint: use the Copy to clipboard button)

Azure - Get the "Directory (tenant) ID"

Last, capture the Directory (tenant) ID to use in configuring Rundeck.

Click "Overview" on the left
Copy the "Directory (tenant) ID" and store it someplace. You will use it in the URL when configuring Rundeck. (Hint: use the Copy to clipboard button)
Copy the Client ID and store it someplace. You will use it as the clientID when configuring Rundeck. (Hint: use the Copy to clipboard button)

Configure Rundeck to use Azure Active Directory for Authentication

Azure Active Directory integration is configured mainly within the rundeck-config.properties file. Below are the required and optional settings to be added. Be sure to substitute your DIRECTORY_TENANT_ID, CLIENT_ID and SECRET_VALUE (Password) that you previously saved. After making the changes to the config file, a server restart is required.

# rundeck-config.properties: Azure SSO
rundeck.sso.loginButton.enabled=true
rundeck.sso.loginButton.title=Login with Azure
rundeck.sso.loginButton.url=oauth/azure
rundeck.security.oauth.azure.autoConfigUrl=https://login.microsoftonline.com/<DIRECTORY_TENANT_ID>/v2.0
rundeck.security.oauth.azure.clientId=<CLIENT_ID>
rundeck.security.oauth.azure.clientSecret=<SECRET_VALUE>
rundeck.security.syncOauthUser=true

# Define the Azure scopes to map
rundeck.security.oauth.azure.scope=openid email profile https://graph.microsoft.com/Directory.Read.All

# Map Azure user detail attributes
rundeck.ssoSyncAttribNames.firstname=given_name
rundeck.ssoSyncAttribNames.lastname=family_name
rundeck.ssoSyncAttribNames.email=preferred_username

# Optional: The follow can be used to make the Azure AD email address as the username
# which enables you to use the email address as the username in ACL policies
#rundeck.security.oauth.azure.principleKeys=preferred_username

Upon first login to Rundeck using Azure SSO an Azure Admin level user will need to consent to the Directory.Read.All permission. Make sure to click the checkbox that asks to consent for the whole organization.

Note: Azure Groups

By default, Azure does not send group information in the SSO token. You can configure Azure to send group information by adding a groups claim to the token configuration in Azure, however this method only supports using the group OID as group identifier, but not the group name.

If you need to sync user groups by group name, you need to enable the Rundeck plugin that uses the MS Graph API to get user/group information. Using this requires additional API permissions that were setup in the App Registration.

To enable this plugin, enable the Enable Azure UserGroupSource Plugin setting in the System Configuration page (config key framework.plugin.UserGroupSource.AzureGroupSource.enabled), or add the following to the framework.properties file:

# framework.properties: Azure SSO
# Map Azure groups by default (can be commented out if not mapping group permissions)
framework.plugin.UserGroupSource.AzureGroupSource.enabled=true

Note: firstname, lastname and email attribute mapping

If your Azure Active Directory attributes are non-standard, you can specify the correct attribute values to use. You can verify the values by selecting the person icon in the upper right corner after logging in, and selecting Profile. If you see NOT SET for any fields, you will need to correct the attribute mappings to your custom settings.

Note: Debugging tips

If you are having trouble with the Azure SSO integration, these additional config file entries will generate helpful debugging information. Adding the following lines to the log4j2.properties* file will produce additional debugging output in the services.log file.

logger.spring_security_oauth.name = org.springframework.security.oauth2
logger.spring_security_oauth.level = debug
logger.spring_security_oauth.additivity = false
logger.spring_security_oauth.appenderRef.stdout.ref = STDOUT

Note: Azure Government

The Azure Groups plugin uses the MS Graph API endpoint to gather the groups. By default it will use the endpoint https://graph.microsoft.com/v1.0/users/. For some Azure environments (Government, etc.) a different endpoint may be needed. (more info)

The endpoint can be changed using the following setting using Configuration Management or the framework.properties file:

# framework.properties: Change the default endpoint
framework.plugin.UserGroupSource.AzureGroupSource.baseApiEndpoint=<NEW_URL>