Abstract
Using EntraId for login enables users to automatically login to the
STP Cloud with their EntraId (M365).
This document describes how to configure the customer’s EntraId as
external Identity Provider for the tenant in the STP Cloud.
Prequisites
- The customer has an Azure Active Directory account
- Access rights in AAD to create an App Registration
- A tenant in the STP cloud exists
- Admin access to that tenant
1) Licensing for EntraId as eIDP
The following license must be added to the tenant.
License needed to use EntraId
Info: These licenses can be requested through the STP Support.
2) In Azure Active Directory
2.1) Add an App Registration
Add an App Registration for the STP-Cloud-Login. Along with that a client secret must be specified.
Info: An app registration can be done here: App Registration in M365
Add an App Registration in M365
2.2) Specify a redirect URL
A redirect URL for the STP-Login App must be specified using the tenant specific subdomain e.g. https://mydomain.stp-cloud.de/identity/signin-microsoft .
Add a redirect URL to App Registration
2.3) Add a client secret for the App
A secret must be added to the App prove the identity for token requests.
Add a client secret to App Registration
Important: Store this client Id and secret in a save location because it will not be displayed again and they will be needed later on!
2.4) Configure API permissions for the STP-Login App
The default permissions and scopes should suffice.
The permissions for the App
2.5) The Endpoints
Take a look at the endpoints for the App. The “OAuth 2.0 authorization endpoint (v2)” and the “OAuth 2.0 token endpoint (v2)” will be needed for further configuration.
The endpoints of the App
3) Identity Admin in the STP Cloud
The Identity Admin
3.1) Add external Identity Provider
Add Azure Active Directory as an identity provider using the values from above.
Configure the Identity Provider
Important: It can take up to an hour for the changes to manifest. Affer that the login screen should look like this:
STP Cloud Login screen with “Microsoft 365” login button
3.2) Individual Account Connection
Clicking on “Login with Microsoft 365” will still show an error:
External login error “Unknown user”
The STP Cloud account must be connected to the M365 account first:
3.3) Connect the user account
To connect your STP user account to the Azure Active Directory
account you need to login to the STP cloud using the local login.
While logged in, go to https://<tenantname>.stp-cloud.de/identity/
(e.g. https://mydomain.stp-cloud.de/identity/)
Connect identity page
While authenticated, click on “Microsoft 365” under “Connect more Identities”. The browser will redirect you to Azure Active Directory where the M365 login can be done. After that the STP-Cloud has to be granted access to Microsoft 365 User Profile.
Grant access for STP-Cloud
Once redirected back, the Microsoft 365 Account is now connected to the STP-Cloud Account.
Info: Alternatively, an administrator can grant consent for all users in the API Permissions section of the app registration in Azure Active Directory.
3.4) Test the connected account
To test the connected account, logout from STP-Cloud and click on the “Microsoft 365” while not authenticated. You will be automatically logged in as the same user of the connected Microsoft 365 account.
3.5) Auto-connection by email claim
Instead of having users individually connect their M365 with their
STP-Cloud account, the admin can enable auto-connect by email
claim.
If enabled, users will automatically have their M365 account connected
to the STP-Cloud account that uses the same email address.
Configure auto-connect users
3.6) Prevent local login
In some circumstances login via an external IDP like AAD should be
the only way to login. “Local login” via email and password should no
longer be possible.
In that case the IDP can be set up to prevent local login.
Prevent local login
Important:
- If this IDP is the only active IDP, the external login is attempted automatically.
- If the external identity is not yet connected and ‘auto-connect by email claim’ is disabled, new users will not be able to login.
- If the configuration at the external IDP is revoked or expired or has any other problem, login into STP Cloud is no longer possible.
- In that case an STP Support Agent has to manually unset the ‘prevent local login’ setting.
- Resource Owner Password Grant logins are exempted from this. They still work with username and password in order to retain agent connectivity (e.g. DMS Mobile DESK, Mobile Time).
4) Known Limitation
Changing the external IDP in IdentityAdmin to authenticate against a
different IDP renders all external identity of that tenant invalid,
because they will have a different external ID in the different
IDP.
Since every user can only connect one external ID per external IDP, they
will have to remove their external ID manually and connect the new
one.
Important: If “prevent local login” is enabled, users will not be able to remove their old external ID and will not be able to login anymore.
Solution
Instead of changing the external IDP to authenticate against a different IDP, remove it and create a new one.
That will automatically remove all connected external IDs.
Users can then connect their external ID manually or have them
automatically connected if “auto-connect” is enabled.
Info: Login at common.stp-cloud.de does not work with single-sign-on. Common subdomain login experiences are used for the STP.Marketplace or the new Office Addins (STP.Documents.Outlook). When a login at common subdomain is attempted for a tenant that has local logins prevented, the browser is redirected to the specific tenant subdomain, where the login with the external IDP can be completed. The browser is then redirected back to the authenticating service (but only if this redirect URI is allowlisted in identity admin). That service gets an auth_code to exchange for an access token. However, the session cookie of the user has been set to the specific tenant subdomain, not the common subdomain. The user is therefore not considered logged in at common subdomain.
Related to