Arcentry Enterprise - Azure AD Authentication
Arcentry Enterprise is the commercial on-premise version of Arcentry. You can learn more about it here or contact us at info@arcentry.com.
Arcentry offers an oAuth2 workflow specifically designed for seamless integration with Azure Active Directory and the wider Microsoft Identity Platform.
It enables users to authenticate with their Single Sign On Credentials against login.microsoftonline.com which will in turn forward a JSON WebToken (JWT) to Arcentry.
Upon receipt of the token, Arcentry executes the following checks:
- Parse the JWT and verify its signature and expiry date
- Determine its version and load the related public key from Microsoft based on the token's Key ID (kid)
- Verify the token against the Public Key
- Ensure the token's audience (aud) matches the configured AD Client ID or one of the configured alternativeAdAudiences
- Check that the token's nonce (one-time key that was generated upon token creation) matches the nonce stored in the database (this can be turned off to allow for token-reuse)
Configuring Azure AD Auth
In order to use Arcentry with Microsoft Identity Platform, set the authType in arcentry-conf.yml to azureAdJwt.
Unfortunately, there's quite a lot more to configure - so let's go through the options one by one:
- showSignupForm, showLoginForm & canResetPassword: As user-accounts are managed by Microsoft, you want to disable sign up and password reset. Leave login enabled though, to allow for internal/admin user login.
- jwtCookieName: Arcentry allows for authentication with a previously issued token. There are a number of ways to pass this token to Arcentry. To read an existing token from a cookie, specify the name of the cookie containing the JWT here and disable checkNonce.
- localStorageBearerTokenKey: Similar to jwtCookieName above, it is possible to use a token that has been previously stored in localStorage. To use this, specify the key of the localstorage item storing the JWT here and disable checkNonce
- azureAdTenantId: The tenant ID for your general AD account
- azureAdClientId: The Application ID for the Azure Enterprise application.
- azureAdClientSecret: This is used to authenticate with Microsoft Graph API to load group names that allow for linking of AD groups with Arcentry groups
- alternativeAdAudiences: Arcentry makes it possible to use tokens that were issued for other audiences. To do so, list the alternative audences here
- checkNonce: if true, Arcentry will issue a one-time ID with every token request. That prevents token reuse attacks, but also makes it impossible to reuse previously issued tokens.
- tokenOrigin: If you pass the token to Arcentry via post-message, specify the origin (base-path of the URL) of the parent window here.
iFrame configuration
Arcentry diagrams are frequently embedded as iFrames into another page or app. But when it comes to Microsoft Identity Platform authentication, that's a problem, since login.microsoftonline.com cannot be loaded in an iFrame.
Arcentry offers a few workarounds to this problem:
Reusing an existing session token from localStorage
Upon login, the Microsoft Identity Platform stores a session token as JWT in localStorage under the key adal.idtoken. Arcentry can read this token if localStorageBearerTokenKey is set to adal.idtoken.
This approach however, only works if the Arcentry iFrame is hosted under the exact same origin as the page that requested the token.
Passing the token to the iFrame
If your embedded iFrame is hosted under a different origin than its parent page, you can pass a JWT to it from the parent page. This can be done in one of two ways:
Passing the token as a query string parameter
To pass the token in the query string, simply add a parameter &id_token=[YOUR_TOKEN] to the URL, e.g.
http://yourdomain.com/app/embed.html?id=c2fd7b9f-2ddd-45b4-bb30-0e8baf7e67c9&id_token=YOUR_TOKEN
Passing the token via Post Message
Post Message is a mechanism to securely pass messages between browser windows and iFrames. Arcentry can use it to pass a JWT stored in localStorage from the parent page to the iFrame. To do this, perform the following steps:
- set the id_token query string parameter to await
- specify the base URL of the parent page as tokenOrigin in arcentry-conf.yml, e.g. https://mydomain.com
- Add a script to the parent-page, e.g.:
<!DOCTYPE html>
<html>
<body>
<iframe
width="800"
height="600"
src="http://localhost:8060/app/embed.html?id=c2fd7b9f-2ddd-45b4-bb30-0e8baf7e67c9&key=8d15dff6658b6473257e101358e9ea8f60f34b489070d8e53c86bcf08b077b7c&id_token=await"
id="arc-iframe"
>
</iframe>
<script type="text/javascript">
const targetElement = document.getElementById( 'arc-iframe' );
const targetWindow = targetElement.contentWindow;
const targetOrigin = ( new URL( targetElement.src ) ).origin;
const message = { jwt: window.localStorage.getItem( 'adal.idtoken' ) };
window.addEventListener( 'message', msg => {
if(
msg.source === targetWindow &&
msg.origin === targetOrigin &&
msg.data === 'ready-for-token'
) {
targetWindow.postMessage( message, targetOrigin );
}
});
</script>
</body>
</html>
About keys in the URL
When an embed is created via the API, it will contain a key=xxx parameter in the URL. This key allows you to override group based permission checks. If a key is present and valid, Arcentry will ignore further permissions and grant access to the embed to any authenticated user. If you remove the key parameter from the URL, Arcentry will ensure that both user and embed share a group with VIEW_EMBED permissions.