This documents describes 2 basic scenarios:

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

In the first case when 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 user logs in, it redirets back to OpenIAM where it gets access to all OpenIAM resources that are available for this user.

When Azure is SP (Service Provider) and 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 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 you will need to go to Azure Active Directory and select 'Enterprise Applications' menu item.

There you select 'New Application':

There you will see 'Create your own application'. Having selected this you will need to give your application some name. This could be any name that makes sense for you. And select 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 like 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 parameters by default. You will also need parameters from section 4 of this page for configuring OpenIAM part.

Configuring OpenIAM

Create authentication provider, use option 'Add OpenIAM as service provider to your IDP'.

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

Validating configuration

To validate configuration you can go to your Enterprise application in Azure -> Single sign on -> SAML and select 'Test' in configuration section 5:

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), you can 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

Configure OpenIAM Authentication provider

Create authentication provider, use option 'Add service to OpenIAM(IDP)'.

Save and download signing public key, share it with Azure. If you want to add Azure as an application in selfservice on Application page you have to specify Application URL attributes. It consists of https://{OpenIAMAddress}/idp/saml2/idp/initiate/{authentication provider ID}. ID can be taken from URL in browser see screenshot:

example of Application URL: https://demo.openiamdemo.com/idp/saml2/idp/initiate/8a80839077ed7cff0177edeefbb2004a

Create a role (or group) in OpenIAM and in its entitlements link it with resource of authentication provider. Assign test user the role (or group) to a test user. Now in selfservice test user will have icon O365 and when he clicks it SSO will be launched.

Configuring Azure

You will need to run PowerShell session to make configurations below. Please start PowerShell console.

Firstly, you should try to load MSOnline module:

Import-Module MSOnline

If you see errors after running command above - you would need to install this module:

Install-Module MSOnline

You will need to take certificate that was issued on OpenIAM side on the previous steps and load it to a PowerShell variable:

[string]$cer = Get-Content 'CERTIFICATE_DOWNLOADED_FROM_OpenIAM'

Than save credentials for your admin account that has permissions to make changes to domain configuration inside Office365:

$credentials = Get-Credential

And run commands similar to 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 domain name that is added to your Office365 and is verified domain. You can check it by going to https://portal.office.com -> Admin -> Settings -> Domains. We will be switching this domain to federated one
• https://demo.openiamdemo.com/ - please replace this value with your OpenIAM instance address
• IssuerUri parameter should include identifier that should be given from OpenIAM side
• $cer - is the certificate that was loaded above

Please also pay attention that OpenIAM address should work using https protocol. This is requirement of Microsoft. Otherwise you will not see error, but you will not get solution working.

Connect-MsolService -Credential $credentials

Set-MsolDomainAuthentication -Debug -DomainName openiamdemo.com -Authentication Federated -ActiveLogOnUri https://demo.openiamdemo.com/idp/saml2/idp/login -SigningCertificate $cer -PassiveLogOnUri https://demo.openiamdemo.com/idp/saml2/idp/login -IssuerUri https://demo.openiamdemo.com/idp/saml2/idp/login/8a8086e467c60f7f0167e067e4d5029f
 -LogOffUri https://demo.openiamdemo.com/idp/saml2/idp/logout -PreferredAuthenticationProtocol Samlp

It may take around a minute for configuration to be applied. After this you can test your setup by trying to log in to Azure/O365 services using username at your domain that was just configured as federated.

Additional information

Verifying domain authentication settings

To check current settings you can use following PowerShell command:

Get-MsolDomainFederationSettings -DomainName openiamdemo.com | Select-Object ActiveLogOnUri, IssuerUri, LogOffUri, PassiveLogOnUri, SigningCertificate

Changing authentication settings If you would need to change any of settings that were set using command avove, you would need to switch domain back to managed and re-run command above, but with changed parameters. The reason is that for now running Set-MsolDomainAuthentication cannot change existing settings. Maybe in future this will be changed.

To switch domain back to federated you can run following command:

Set-MsolDomainAuthentication -DomainName openiamdemo.com -Authentication Managed -Debug

Handling errors and misconfiguration

• Please make sure that you run OpenIAM using HTTPS
• If you see error 'Set-MsolDomainAuthentication : Invalid value for parameter. Parameter Name: federationSettings.' - this could be caused by wrong certificate formatting. Please make sure that it does not have any additional whitespaces or chars.