Microsoft OAuth2 Login – Setup

Enabling Microsoft OAuth2 login in SELMA allows users to authenticate using their Microsoft accounts instead of traditional username/password credentials. This provides a seamless single sign-on experience for users who have Microsoft 365 or Azure Active Directory accounts, improving security and user experience.

Note: The below instructions serve as a guide only – please ask your IT Team/Provider about what’s best for your organisation.

Azure/Entra Application

For this to work we need a few credentials for an ‘app’ in Azure specifically configured for authentication purposes.

Please go to https://portal.azure.com/#home and register an application (https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade).

It just needs to be named at this point – something like “SELMA OAuth2 Login” to make it easy to identify it in the future. The remaining fields can be left with their default values.

Once created, note the following details from the App:

• Application (client) ID
• Directory (tenant) ID
• Client Secret – this still needs to be added to the App (see below).

Client Secret

1. Add new client secret – click “Add a certificate or secret”
2. Set a name and expiry duration for the new secret
   • Set a reminder somewhere to create a new secret before the expiry. Update the secret with the SELMA team before the expiry date to prevent issues.
3. “Add” the secret
4. Copy the secret value immediately at this point – as it won’t be shown again – to be able to send it to the SELMA team later.
   • If you can’t copy the secret anymore (if the page was refreshed, for example), please redo the entire client secret creation step.

Redirect URL

1. Return to the “Overview” page and add a redirect URL.
2. Click “Add Platform” and select the “Web” option.
3. You’ll be asked to enter a redirect URL now. Use the following format:
   • Example: https://subdomain.selma.app/connect/azure/check
   • NB. Replace “subdomain” with your actual SELMA subdomain
4. Click the “Configure” button to save the changes.

Permissions

The App also needs to have the appropriate permissions to request from the user for authentication purposes.

By default, it should already have the “User.Read” (delegated) permission – but if not, follow the steps below to add it:

1. Add the permissions by clicking “API Permissions” → “Add a permission” → “Microsoft Graph”.
2. Choose the “Delegated permissions” option, as the integration needs to perform authentication on behalf of the user.
3. Ensure the “User.Read” permission is selected – search & select it if not selected yet.
   • This permission allows the application to read the user’s profile information for authentication purposes.
4. Remember to click “Add permissions”!

Next Steps

Once you have completed the Azure application setup and obtained your credentials, contact the SELMA team with the following information:

• Application (client) ID
• Directory (tenant) ID
• Client Secret

The SELMA team will then configure the OAuth2 integration for your SELMA instance.

Test the Integration

After the SELMA team has configured the integration:

1. Log out of SELMA
2. Go to the SELMA login page
3. Click on the “Microsoft” login button and you’ll be redirected to Microsoft’s login screen
4. Sign in with your Microsoft account
5. Grant permission to SELMA to access your profile information, if needed
6. You should be redirected back to SELMA and logged in successfully

Important Notes

• Setup Process: The Azure App setup is done by your organisation, but the SELMA integration is configured by the SELMA team
• Credentials Security: Store your Application ID, Directory ID, and Client Secret securely before sending them to the SELMA team
• Email Matching: Users must have the same email address in both SELMA and their Microsoft account for the login process to work
• Secret Expiry: Remember to renew your client secret before it expires and provide the new secret to the SELMA team

Done! ✅

The Microsoft App setup is now complete. Once you’ve provided the Application ID, Directory ID, and Client Secret to the SELMA team and they’ve configured the integration, users will be able to log in using their Microsoft accounts by clicking the “Login with Microsoft” button on the SELMA login page.

Troubleshooting

• “Invalid client” error: Check that the correct Application ID, Directory ID, and Client Secret were provided to the SELMA team
• “Redirect URI mismatch”: Ensure the redirect URI in Azure exactly matches the format https://subdomain.selma.app/connect/azure/check
• Secret expiry issues: If authentication suddenly stops working, check if the client secret has expired in Azure