Skip to main content

Security

SAML Authentication

Introduction

SAML 2.0 Protocol is an XML based standard for exchanging authentication information between security domains. It has two roles:

  • Provider (Identity Provider)
  • Consumer (Service Provider)

The following list depicts the basic communication workflow:

  1. The user wants to use the service of the service provider and goes to their portal.
  2. The service provider directs the user to its identity provider for the user the authenticate with them.
  3. The user authenticates themselves by the identity provider.
  4. The identity provider delegates a token and sends the user back to the service provider.
  5. The service provider can use the token to identify the user and provide them with their services.
The job of the admins is to configure the information necessary on both the provider and consumer sides so that these platforms/domains can communicate with one another.
  • MApp Enterprise is the Service Provider, hence the Consumer.
  • Identity Providers such as “Azure AD”, “Keycloak”, “Okta”, or any other provider that supports SAML protocol should be applicable and can be used to authenticate with MApp Enterprise.

Configuration on M.App Enterprise (Consumer / Service Provider)

The configuration of SAML Protocol for MApp Enterprise can be found on Management contexts create/edit tenant formular, since tenants can have different authorization methods. Following are the formular fields for the protocol that appear after choosing SAML as the third-party authorization integration:

IDP Metadata URL

⚠️
This field is required

The URL for the metadata XML file, that is provided by the Identity Provider. It should be in URI format. Example: https://identityprovidername.com/serviceprovidername/saml/metadata

Issuer

⚠️
This field is required

Issuer is the name of the identity issuing app at Identity Provider. Identity Provider can hold metadata of multiple service providers. The name of the one associated with MApp Enterprise is here necessary.

Signature Algorithm

⚠️
This field is required

The hash algorithm used for digitally signing login / logout processes. SHA256 and SHA512 are currently supported. This value should be equal to the signature algorithm value that is set in the configuration of the Identity Provider’s MApp Enterprise connection.

Decryption Certificate

💡
This field is optional

If the communication with the Identity Provider is encrypted by an encryption certificate, the decryption certificate (aka private key) should be uploaded here. Allowed file endings are “.pfx” and “.p12”.

Decryption Certificate Password

💡
This field is optional

The password that would let the decryption certificate be read, if the decryption certificate is password protected. If not, this field should be left blank.

Studio Role

💡
This field is optional

Users are normally allowed to authorize themselves into a tenant’s Apps context with the third-party authorization protocol. Studio Role is a shared setting between all third-party authorization protocols which allows a tenant’s Studio context to be authorized with the selected protocol too, if the authorized user has a role value corresponding to the value specified in this field. In the case of SAML, the Identity Provider should insert this value with the key “role” or “group” (like mentioned in Table 3) as a key-value pair in the returned authorization token.

Prefer Third Party login

💡
This field is optional

This setting allows Mapp Enterprise to configure Studio Apps to enforce selected third-party authorization as the only method to login into a tenant’s Apps context. Users can not create user accounts directly with Mapp Enterprise but will skip MApp Enterprise Login Page and will be directed to the third-party provider immediately, be it Azure AD, OpenID or SAML in this case.

Configuration on Identity Provider

Client ID

Client ID or App ID both correspond to “Issuer” from service provider.

Redirect URL

After the Identity Provider authorizes the user’s login request, it needs to send the user back to the service provider, MApp Enterprise. The redirect URL of the service provider must be configured on the identity provider for this to occur. Some Identity Providers allow URLs containing wild cards (*), whereas some do not. Redirect URL Examples for MApp Enterprise that needs to be whitelisted are shown on the following table:

Table 1: Redirect URL examples
Condition Redirect URL Example
If wild card (*) is allowed https://yourdomain.com/*
If wild card (*) is not allowed https://yourdomain.com/Apps/?tenant=yourtenantname
If wild card (*) is not allowed and “Studio Role” is defined in M.App Enterprise Configuration https://yourdomain.com/Apps/?tenant=yourtenantname

AND

https://yourdomain.com/Studio/?tenant=yourtenantname

Assertion Consumer Service Binding

The Identity Provider will communicate with the consumer through either POST or Redirect bindings. The correct endpoint link must be entered in the configuration formular of Identity Provider for the given binding. If only one field is provided, test and choose the one that works since which binding will be defaulted to depends on the Identity Provider. The following table shows the different MApp Enterprise endpoints differentiated by binding types:

Table 2: Service Provider Endpoints by Identity Provider’s ACS binding type
ACS Binding Type Service Provider Endpoint
HTTP-Post https://yourdomain.com/api/v1/saml/yourtenantname/post-assertion
HTTP-Redirect https://yourdomain.com/api/v1/saml/yourtenantname/redirect-assertion

Customizing Authorization Token

Once a user logs into a tenant’s Apps context using SAML, a new MApp Enterprise User is created and saved in our database using the information from authorization token sent by Identity Provider if this is their first-time logging in. The authorization token can be filled with additional information in key-value pairs that will be used during the creation of MApp Enterprise User with these values. The keys of the pairs and their associated properties are listed as follows:

Table 3: Keys for given MApp Enterprise user properties
KEYS (Comma seperated) PROPERTY
givenname,firstname,urn:oid:2.5.4.42 First Name
familyname,surname,lastname,urn:oid:2.5.4.4 Last Name
email,urn:oid:1.2.840.113549.1.9.1 Email
language,locale,culture Language
role,group User Role

Example key-value pairs inside authorization token:

urn:oid:2.5.4.42: John
surname: Doe
email: john.doe@test.com
culture: en-US
group: MApp_Tester

On consequent logins, the already created MApp Enterprise User will be used, and the user’s settings on MApp Enterprise after their creation will not be overwritten by changes done inside new authorization tokens.