Book a Demo
Prev Next

Walkthrough: OpenID with Azure

This walkthrough helps you to set up Enterprise Architect to log in to models with Single-Sign-On (SSO) using Azure users via OpenID.

The walkthrough will detail the minimum setup required to get a working example. There are numerous extra options available in Azure that can be customized to suit the requirements of your organization.

This guide requires Enterprise Architect version 16 or later to work with claims in the ID token, and to allow automatic creation of new users based on their group memberships.

Add an App Registration for Enterprise Architect

  1. Log in to the Azure portal:
  2. Click the side menu drop-down and click on 'Azure Active Directory'.
    Shows the selection of Azure Active Directory menu
  3. Click on 'App registrations' and on the New registration button.
    Shows how to create a new App Registration in Azure
  4. Fill in the form.
  5. Give the application a name - this will be visible to end users when they consent to the app (if applicable, the app can be given global consent by an administrator).
  6. Select the 'Single tenant' radio button (unless you understand the use of 'Multitenant').
  7. Redirect URI:
         -  Select the 'Public client/native (mobile & desktop)' option from the drop-down option
         -  Type in 'http://localhost:8888/openid/callback'
         -  Click on the Register button.
    Shows details to be entered when creating a new 'app registration' in Azure for use with OpenID

Application Details: URL, Client ID

After the new app registration is created, you should see the details of the application. Copy the 'Application (client) ID'. This will be pasted into Enterprise Architect (step 6 in this procedure).

Details of the App Registration in Azure
  1. Open Enterprise Architect and open the model; it is assumed that the model has been set to use model security already.
  2. Log in with an account that has permissions to edit users and groups (for example, 'admin').
  3. Click on the 'Settings > Security > Users' ribbon option.
  4. In the 'Global Options' panel select the 'Accept OpenID Authentication' checkbox.
  5. Click on the Configure OpenID button.
    Configure Enterprise Architect model to use OpenID
  6. Paste the copied 'Application (client) ID' into the 'Client ID' field.
    The OpenID configuration settings for Azure
  7. Add 'profile' to the 'Scope' field to allow the user's full name to be passed back.
  8. Add 'offline_access' to the 'Scope' field to allow users to refresh their authentication tokens automatically using 'refresh tokens'.
  9. For this walkthrough we will match against 'upn'; type 'upn' in the 'Claim to Match to Local User' field.
  10. (Optional) Add 'groups' to the 'Claim to Match to Local Groups' field. See the 'Automatically create or modify Windows or OpenID Users' option section later in this topic, on how to use groups to automatically create or modify users based on their OpenID group membership.
  11. Select the 'Use ID Token for claims' checkbox. Deselect the 'Use User Info for claims' checkbox.

    (Note: In Release 16 or later it is now possible to get claims direct from the ID token rather than via the User Info endpoint. This has many advantages, including being more compliant with the standard (claims in the User Info endpoint are optional and aren't customizable in Azure) as well as reducing the number of internet calls to the OpenID provider.)
  12. In Azure, click on 'Endpoints'. This lists the URL 'endpoints' that applications can connect to Azure with.
  13. Copy the URL for 'OpenID Connect metadata document', but exclude the '.well-known/openid-configuration' portion.
  14. In Enterprise Architect, paste the URL into the 'OpenID URL' field.
    Shows the endpoints for an Azure App Registration

Add API Permissions

  1. Click on 'API permissions'.
  2. Click on 'Add a permission'.
    Select 'API permissions', 'Add a permission'
  3. Click on 'Microsoft Graph'.
    Select 'Microsoft Graph'
  4. Click on 'Delegated permissions'.
    Select 'Delegated permissions'
  5. Select all permissions under 'OpenId permissions': 'email', 'offline_access', 'openid' and 'profile'.
    Select all OpenID API permissions

Claim to Match to Local User

Enterprise Architect will log a user on if the claim returned from the OpenID provider matches the user login in the Enterprise Architect model. Care should be taken to use a secure claim; that is, one that can not be modified by an end user, but only by an administrator of the Azure system. By default, UPNs cannot be modified by a regular user.

There should be some consideration of which claim will be used to match to the local user login in Enterprise Architect. Microsoft recommends that a stable GUID (such as 'sub' or, 'oid') should be used to avoid any issues with name changes that might affect an email, username or UPN. However, a UPN allows for a human-readable user login, which might be preferable.

With no further configuration you can match to either the 'oid' or 'sub' claims (as recommended by Microsoft) as these are always passed back in the ID token. To enable matching against the UPN or email address of the user, further configuration is required.

If the option to allow automatic creation of users in Enterprise Architect is to be used, then it is also required for a user to have a first and last name, and for these to be passed back to Enterprise Architect in the token. These are optional claims that need to be manually selected too.

  1. Click on 'Token configuration'.
  2. Click on 'Add optional claim'.
    Select 'Token configuration', 'Add optional claim'
  3. Select 'ID'.
  4. Select 'family_name, given_name'.
  5. Optionally select another claim that will be used to match the user login in Enterprise Architect. Common choices are 'upn', 'email', 'verified_primary_email'.
    For this walkthrough, select 'upn'.
  6. Click on 'Add'.
    Select the required additional claims to be added to the ID token

Add User to Azure

This walkthrough will add a single user to demonstrate OpenID authentication. Full user setup is outside the scope of this guide.

  1. Back in the main 'Active Directory' section, click on 'Users'.
  2. Click on 'New user'.
    Select 'Users', click 'New user'
  3. Fill in the details for the new user. Here we create a simple test user:
         -  Make a note of the password
         -  Click on 'Create'
    Fill in the details for the new user

Test the Configuration in Enterprise Architect

This is enough to get a simple example working from within Enterprise Architect.

  1. Back in Enterprise Architect, click on the Test button in the Configure OpenID... window.
  2. Click on 'Login with OpenID'.
    Test the connection in Entperprise Architect
    This will pop up your internet browser and require you to log in to your Microsoft Account (for Azure).
  3. Log in as the newly created user. (Note that your credentials might have been cached by the browser; log out of all Microsoft services and close your browser before performing this test.)
  4. You might be prompted to create a new password. Again, make note of the new password for later logins.
  5. You will be prompted to consent to allow the new Azure App access to your profile.
    (Note that it is possible for an administrator in Azure to consent to the application on behalf of all users.)
    The Azure consent screen to allow the Azure App access to your profile
  6. The browser will now show a success message. You can close the browser and return to Enterprise Architect.
  7. Enterprise Architect will show a success message with the details matched in the claims.
    Success message in the browser after logging in to Azure
  8. Click on the OK button on the success message.
  9. Click on the OK button on the Configure OpenID... window to save the settings.

Add Matching User to Enterprise Architect

Add a new user to Enterprise Architect with a matching 'Login' field.

  1. Select the 'Settings > Security > Users' ribbon option.
  2. Copy the User Principal Name (UPN) of the Azure user and paste it into the 'Login' field.
  3. Type in a name (this does not need to match the Azure user's name).
  4. Click on the Save button.
    Add a matching user to Enterprise Architect

Test Logging in to Model

  1. Close and re-open Enterprise Architect.
  2. Open the model.
  3. The same OpenID Authentication screen displays; click on 'Login with OpenID'.
    Login screen for OpenID in Enterprise Architect
    Nb: If the standard Login to EA Repository dialog appears rather than the OpenID Authentication dialog, unselect the option Hide OpenID logon window in:
  4. If required, log in to Azure in the internet browser, then close the browser and return to Enterprise Architect where you are now logged in as the new user.
  5. You can also confirm the logged in user at the top-right of Enterprise Architect. The logged in user's name appears with a drop-down menu of user security options.
    The logged in user is displayed top-right of Enterprise Architect
  6. The System Output window will detail your attempted logins. Note that 'groups' did not match, as that has not been configured at this point in the walkthrough.
    System Output after successful login with Azure OpenID

At this point, if you are going to manually add users to Enterprise Architect then there is no need to complete any more steps.

If you want to enable the 'Automatically create or modify Windows or OpenID Users' option then continue to the next section.

'Automatically create or modify Windows or OpenID Users' option

This option allows you to set up groups in Azure, and link the groups to local groups in Enterprise Architect. Users can then be automatically created when they first attempt to log in. New and existing users will have their group membership updated whenever they log in, to match the linked groups in Azure.

Add Group Claim to ID Token

In a similar way to how the UPN and names claims were added, add a groups claim to the ID token.

  1. Click on the 'Azure > Azure Active Directory > App registrations' option.
  2. Click on your new application.
  3. Select 'Token configuration' from the sidebar.
  4. Click on 'Add groups claim'.
  5. Select 'Security groups'.
  6. Expand the ID section.
  7. [Optional] As with choosing a claim to match to the Enterprise Architect login name, some consideration should be given to the claim used to match groups to local groups in Enterprise Architect. The default selection here is 'Group ID'. This is a GUID string that can be easily copied around and will stay the same even if the group name changes. However, it is less clear which group is matched when viewing the linkage in Enterprise Architect, so one of the sAMAccountName settings might be more appropriate. In this guide we will use the default selection of 'Group ID'.
  8. Click on the Add button.
    Add the group claim to the ID Token

Add New Azure Group

In the 'Azure Active Directory':

  1. Select 'Groups' from the sidebar menu.
    Select the 'Group' menu from the sidebar
  2. Click on 'New Group'.
    Click 'New group' to add a new group
  3. Leave the 'Group type' set to 'Security'.
  4. Type in a name for the group, such as 'EA Users', 'EA Administrators' or 'EA Read-only'.
  5. Click on 'No members selected' to add the test user to the group.
    Fill in the details of the new group
  6. Select the test user and click on 'Select'.
    Select the users to be added to the group
  7. Click on 'Create' to finish creating the new group.
  8. Refresh the list of groups (this can take up to 30 seconds).
  9. Copy the group's 'Object Id' for use in the next step.
    Copy the Object ID of the new group
  10. See the earlier Application Details: URL, Client ID section.

Link Group in Enterprise Architect

  1. Open Enterprise Architect.
  2. Open the model; cancel the OpenID login and login as an administrator.
  3. Select the 'Settings > Security > Groups' ribbon option.
  4. Create a new group. Name and description do not need to match the name in Azure.
  5. Paste the Azure group's 'Object ID' into the 'OpenID Group' field.
  6. Click on the Save button to create the new group.
    Link the Azure group to a new Enterprise Architect group

Enable the 'Automatically create or modify Windows or OpenID Users' option:

  1. Close the 'Groups' tab.
  2. Select the 'Settings > Security > Users' ribbon option.
  3. Select the 'Automatically create or modify Windows or OpenID Users' option.
    Tick the option to 'Automatically create or modify Windows or OpenID users'

Now is a good time to re-test the OpenID configuration to check that groups' claims are present in the ID Token, and that the group linkage is correct.

  1. Click on the 'Configure OpenID...' option.
  2. If 'groups' is not already shown in the 'Claim to Match to Local Groups' field, type it in.
  3. Click on the Test button.
  4. Click on 'Login with OpenID'.
  5. Log in to Azure, if required by the browser.

The result will show in Enterprise Architect, showing the user's name as well as the Azure group and the local Enterprise Architect group that it is linked to

Results of OpenID test

Final Test

To test the 'Automatically create or modify Windows or OpenID Users' option:

  1. Close and re-open Enterprise Architect.
  2. Log in to the model using OpenID. The System Output window will indicate any automatic creation of users, and any group assignments based on linked OpenID groups.
    The System Output window showing automatica group assignment from linked OpenID groups