There are two possible configuration scenarios for Azure SSO:

• Azure is IDP and OpenIAM is SP.
• Azure is SP and OpenIAM is IDP.

In the first case when a user is trying to reach OpenIAM and this user is not authenticated - user is being redirected to Azure and is asked to log in to Azure. After the user logs in, it redirects back to OpenIAM where it gets access to all OpenIAM resources that are available for this user.

When Azure is SP (Service Provider) and the user tries to log in to Azure not being authenticated - it is being redirected to OpenIAM and should log in using OpenIAM credentials. When this is done the user is redirected back to Azure and can access own account.

Azure is IDP and OpenIAM is SP

This tutorial is split into 2 parts - configuring Azure side and configuring OpenIAM side.

Configuring Azure

Firstly, go to Azure Active Directory and select Enterprise Applications menu item.

There, select New Application:

There you will see Create your own application. Having selected this, give your application some name. This could be any name that makes sense for you. After, select the radio button saying that this will be a custom application.

After application is created, you would need to go to Single sign-on menu item and press SAML:

There you need to define basic SAML settings similarly to below. Please note, below values are just examples and you will need to put your values. Explanation of values will be given below.

• Identifier (Entity ID) - should be some value that uniquely identifies your application (this will become SAML Issuer Name in OpenIAM configuration)
• Reply URL (Assertion Consumer Service URL) - should follow pattern https://{OpenIAMAddress}/idp/saml2/sp/login
• Sign on URL - should be the same as above, but include issuer parameter that should be equal to identifier. Example: https://{OpenIAMAddress}/idp/saml2/sp/login?issuer=identifierOfApplication
• Logout Url - should follow pattern https://{OpenIAMAddress}/idp/saml2/sp/logout

You can leave the rest of the parameters by default. You will also need parameters from section 4 of this page for configuring the OpenIAM part.

Configuring OpenIAM

To create an authentication provider, use Add OpenIAM as service provider to your IDP option.

Create a role (or group) in OpenIAM and in its entitlements link it with the resource of the authentication provider. Assign the test user the role (or group) to a test user.

Validating configuration

To validate configuration, go to your Enterprise application in Azure > Single sign-on > SAML and select Test in configuration section 5, as indicated below

Additional information

By default, Azure users should be explicitly assigned to your application to be able to sign in using SAML. You can add new users or groups using your Enterprise application in Azure > Users and Groups. Or if you want to allow anyone to access this application inside your organization (without setting users explicitly), go to your Enterprise application in Azure > Properties > set Assignment required? to No.

If you would like to redirect users from login page of OpenIAM automatically to Azure login page you should add redirection URL for pattern idp/login in needed content provider like:

https://demo.openiam.com/idp/saml2/sp/login?issuer=my_issuer

Azure is SP and OpenIAM is IDP

For this scenario, You will need to run a PowerShell session to make configurations below. Hence, begin with starting the PowerShell console.

1. Try to load Microsoft.Graph module with the following command.

Import-Module Microsoft.Graph

If you see errors after running command above - install Microsoft.Graph module with the command below.

Install-Module Microsoft.Graph

2. Another pre-requisite step is connecting to your Azure tenant with the following commands.

Connect-MgGraph -Scopes "Domain.ReadWrite.All", "Directory.AccessAsUser.All", "Directory.ReadWrite.All", "User.ReadWrite.All"

Scopes above allow you to perform actions with domains and users to change their settings.

3. Take certificate that was issued on OpenIAM side on the previous steps and load it to a PowerShell variable by means of command below.

[string]$cer = Get-Content "path_to_downloaded_certificate_from_OpenIAM"

4. Run commands similar to ones given below. Please, pay attention that you would need to set your own values. In commands below we have used following just as examples:

• openiamdemo.com - this is a domain name that you are going to federate with OpenIAM.

• https://demo.openiamdemo.com/ - please replace this value with your OpenIAM instance address.
• The IssuerUri parameter should include an identifier that should be given from the OpenIAM side.
• $cer - is the certificate that was loaded above.

Please also pay attention that OpenIAM addresses should work using https protocol as per Microsoft requirement. Otherwise you will not see errors, but you also will not get a solution working.

New-MgDomainFederationConfiguration -DomainId " openiamdemo.com" -ActiveSignInUri "https://demo.openiam.com/idp/saml2/idp/login" -PassiveSignInUri "https://demo.openiam.com/idp/saml2/idp/login" -IssuerUri "https://demo.openiam.com/idp/saml2/idp/login/ea8081f397a1de3d01987a2748493925" -SignOutUri "https://demo.openiam.com/idp/saml2/idp/logout" -PreferredAuthenticationProtocol "saml" -SigningCertificate $cer -FederatedIdpMfaBehavior "rejectMfaByFederatedIdp"

It may take around 15 minutes for configuration to be applied and it may get applied faster/slower in one region than in others. To test you can try to access any Azure/O365 service (for example, portal.office.com) and input any username@[yourdomain] where yourdomain is the domain name that you configured for federation. Instead of a window for a password input you should get redirected to OpenIAM.

User sign on requirements

To be able to sign in to Azure using OpenIAM as IdP an Azure user should have an ImmutableId (OnPremisesImmutableId is property of Microsoft.Graph module) defined in its profile that should match the value defined in OpenIAM.

When you configure federation for the first time and you already have some existing users in your tenant most probably you will need to set an ImmutableId for your user(s). You can validate if your user has the below property defined with the commands below.

Get-MgUser -UserId [your_user]@[your_domain] -Property OnPremisesImmutableId | Format-List *

If OnPremisesImmutableId is empty you will need to set it. You can use the same value as the UserPrincipalName. To update this property you can use the following.

Update-MgUser -UserId [your_user]@[your_domain] -OnPremisesImmutableId [your_user]@[your_domain]

Troubleshooting

Below is the list of most frequent errors that was encountered during the federation setup.

• AADSTS50107 error it may mean that while setting up federation you might have specified the `DomainName’ parameter not in the lowercase.
• AADSTS51004:The user account … does not exist in …. Your user does not have OnPremisesImmutableId parameter and that is why Azure cannot make a match between your OpenIAM user and an Azure one.
• Insufficient privileges to complete the operation. It is either your user does not have sufficient permissions or you did not set -Scopes parameter while running Connect-MgGraph.
• After installing Microsoft.Graph module you still see an error when you want to use it: […] is not recognized as the name of cmdlet, function…. Please make sure that you do not run x86 PowerShell console, but a regular (x64) one.

Just-In-Time provisioning

Just-In-Time (JIT) provisioning in the context of Security Assertion Markup Language (SAML) refers to the process of creating a user account in an application or system at the moment of user authentication if the account does not already exist. Instead of pre-provisioning user accounts in every service or application, the service can automatically create an account based on the information provided in the SAML assertion when the user logs in for the first time. This can simplify the onboarding process for new users and reduce administrative overhead.

Here's how JIT provisioning generally works in the context of SAML:

1. Initial Login: A user tries to access a service provider (SP), but they don't have an account there.
2. SAML Authentication: The service provider redirects the user to the identity provider (IdP) to authenticate. The user logs in to the IdP.
3. SAML Assertion: Upon successful authentication, the IdP sends a SAML assertion back to the service provider. This assertion contains the user's attributes, like their name, email, roles, or any other necessary information.
4. Account Creation: The service provider checks if there's an existing account for the user. If not, it uses the information from the SAML assertion to automatically create a new user account.
5. Access Granted: The user gains access to the service, either using their pre-existing account or the newly created one.

Benefits of JIT provisioning include:

• Reduced Administrative Overhead: No need to manually create accounts for each user in advance.
• Seamless User Experience: New users can get immediate access to services without waiting for accounts to be set up.
• Reduced Orphaned Accounts: Since accounts are created when needed, there's a lower chance of having unused accounts that can be a security risk.

However, it's worth noting that JIT provisioning can also introduce challenges, such as:

• Attribute Mapping: Ensuring that attributes provided by the IdP match what's expected by the SP.
• De-provisioning: While JIT handles automatic account creation, it doesn't address the removal of accounts when users leave an organization or change roles.
• Role Management: The SAML assertion should provide enough information to assign the correct roles or permissions, which might require coordination between the SP and IdP.

When implementing JIT provisioning with SAML, it's essential to plan out the provisioning process, handle potential edge cases, and ensure that the security implications of automatic account creation are fully understood and addressed.

The JIT provisioning can be configured by inserting a respective groovy script in the service provider editing window, as indicated below.

The example of a respective groovy script is given below.

import org.apache.commons.lang.StringUtils
import org.openiam.base.response.list.GroupListResponse
import org.openiam.base.response.list.RoleListResponse
import org.openiam.base.ws.MatchType
import org.openiam.base.ws.SearchParam
import org.openiam.idm.searchbeans.GroupSearchBean
import org.openiam.idm.searchbeans.RoleSearchBean
import org.openiam.idm.srvc.role.dto.Role
import org.openiam.idm.srvc.user.dto.UserStatusEnum
import org.openiam.srvc.am.GroupDataWebService
import org.openiam.srvc.am.RoleDataWebService
import org.springframework.context.ApplicationContext

import javax.annotation.Resource
import java.util.List;

import org.openiam.idm.srvc.meta.dto.MetadataType;
import org.openiam.idm.srvc.user.dto.User;
import org.openiam.ui.groovy.saml.AbstractJustInTimeSAMLAuthenticator;
import org.opensaml.saml2.core.Attribute;
import org.opensaml.xml.schema.XSString;
import org.opensaml.xml.schema.XSInteger;
import org.apache.commons.collections4.CollectionUtils;
import org.apache.commons.lang3.RandomStringUtils;
import org.opensaml.xml.schema.impl.XSAnyImpl;

class TestJustInTimeSAMLAuthenticator extends AbstractJustInTimeSAMLAuthenticator {

    final private String userTypeId = "DEFAULT_USER"; // user type
    final private String accessRoleId = ""; // role id to link user with auth provider
    final private String managedSysId = ""; // managed sys id of your groups in OpenIAM

    @Resource(name = "roleServiceClient")
    protected RoleDataWebService roleServiceClient;

    @Resource(name = "groupServiceClient")
    protected GroupDataWebService groupServiceClient;

    @Override
    protected MetadataType getEmailType(final List<MetadataType> types) {
        return types.get(0);
    }

    @Override
    protected String getFirstName() {
        if (CollectionUtils.isNotEmpty(response.getAssertions()) && CollectionUtils.isNotEmpty(response.getAssertions().get(0).getAttributeStatements())) {
            for (final Attribute attribute : response.getAssertions().get(0).getAttributeStatements().get(0).getAttributes()) {
                if ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname".equalsIgnoreCase(attribute.getName()))
                    return ((XSAnyImpl) attribute.getAttributeValues().get(0)).getTextContent();
            }
        }
        return RandomStringUtils.randomAlphanumeric(5);
    }

    @Override
    protected String getLastName() {
        if (CollectionUtils.isNotEmpty(response.getAssertions()) && CollectionUtils.isNotEmpty(response.getAssertions().get(0).getAttributeStatements())) {
            for (final Attribute attribute : response.getAssertions().get(0).getAttributeStatements().get(0).getAttributes()) {
                if ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname".equalsIgnoreCase(attribute.getName()))
                    return ((XSAnyImpl) attribute.getAttributeValues().get(0)).getTextContent();
            }
        }
        return RandomStringUtils.randomAlphanumeric(5);
    }

    @Override
    protected String getEmail() {
        if (CollectionUtils.isNotEmpty(response.getAssertions()) && CollectionUtils.isNotEmpty(response.getAssertions().get(0).getAttributeStatements())) {
            for (final Attribute attribute : response.getAssertions().get(0).getAttributeStatements().get(0).getAttributes()) {
                if ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress".equalsIgnoreCase(attribute.getName()))
                    return ((XSAnyImpl) attribute.getAttributeValues().get(0)).getTextContent();
            }
        }
        return null;
    }

    protected void populate(final User user) {
        user.setStatus(UserStatusEnum.ACTIVE);
        user.mdTypeId = userTypeId;
        user.addRole(accessRoleId);

        final List<String> groupIds = this.getGroupsFromResponse();
        if (CollectionUtils.isNotEmpty(groupIds)) {
            groupIds.forEach {user.addGroup(this.getGroupIdByName(it, managedSysId))}
        }
    }

    private String getGroupIdByName(String name, String mngSysId) {
        if (StringUtils.isNotBlank(name)) {
            final GroupSearchBean groupSearchBean = new GroupSearchBean();
            groupSearchBean.setNameToken(new SearchParam(name, MatchType.EXACT));
            groupSearchBean.setManagedSysId(mngSysId)
            final GroupListResponse response = groupServiceClient.findBeans(groupSearchBean, null, 0, 1);
            if (response != null && CollectionUtils.isNotEmpty(response.getList())) {
                return response.getList().get(0).getId();
            }
        }
        return null;
    }

    private List<String> getGroupsFromResponse() {
        final List<String> roleNames = new ArrayList<>();
        if (CollectionUtils.isNotEmpty(response.getAssertions()) && CollectionUtils.isNotEmpty(response.getAssertions().get(0).getAttributeStatements())) {
            for (final Attribute attribute : response.getAssertions().get(0).getAttributeStatements().get(0).getAttributes()) {
                if ("attr_here".equalsIgnoreCase(attribute.getName())) {
                    attribute.getAttributeValues().forEach {
                        roleNames.add(((XSAnyImpl) it).getTextContent());
                    }
                }
            }
        }
        return roleNames;
    }

    private String getRoleIdByName(String name, String mngSysId) {
        if (StringUtils.isNotBlank(name)) {
            final RoleSearchBean roleSearchBean = new RoleSearchBean();
            roleSearchBean.setNameToken(new SearchParam(name, MatchType.EXACT));
            roleSearchBean.setManagedSysId(mngSysId);
            final RoleListResponse response = roleServiceClient.findBeans(roleSearchBean, null, 0, 1);
            if (response != null && CollectionUtils.isNotEmpty(response.getList())) {
                return response.getList().get(0).getId();
            }
        }
        return null;
    }

    private String getRoleFromResponse() {
        if (CollectionUtils.isNotEmpty(response.getAssertions()) && CollectionUtils.isNotEmpty(response.getAssertions().get(0).getAttributeStatements())) {
            for (final Attribute attribute : response.getAssertions().get(0).getAttributeStatements().get(0).getAttributes()) {
                if ("attr_here".equalsIgnoreCase(attribute.getName()))
                    return ((XSAnyImpl) attribute.getAttributeValues().get(0)).getTextContent();
            }
        }
        return null;
    }
}