= Instructions =
<!-- DO NOT MODIFY THE NAME OF THIS SECTION, BUT REMOVE IT IF NOT REQUIRED -->
The customer's Identity Provider must know == Login ==As explained in the [[Single_Sign-On]] article, we want the mobile application to receive a token of authenticity from an authority the user has provided their credentials to. Next, the mobile application should ask the USAM web service to accept this token as credentials and establish a {{UBIK}} as a Service Providersession. In case of SAMLOf course, the USAM web service must verify whether the token is valid. If so, we need to provide an SSO mediator server internal {{UBIK}} login object is created for the user, if it doesn't exist yet.This can be customized in order to relay SAML responses for add further information to the client; this is our ACS login object (Assertion Consumer Servicelike a name, group relations or other arbitrary information). In case of OIDC, the client app interacts with the OIDC provider directlyor to restrict which users may log in, now that their identity is verified.
There are two major use-cases for SSOTo implement this, the following steps must be done:* Authentication: Establishing {{UBIK}} must be registered as a client application (or re-using an SSO session with an external "service provider" in SAML) at the customer's authority or identity provider (logging inIdP). * Authorization* The service engineer must provide a callback URL at which we want to receive the result. In case of OIDC, this is the app's deep link URL "com.augmensys.ubik: Interaction //SSO". For SAML, an intermediate server (assertion consumer service, ACS) is required to relay the token for the app - we provide the {{UBIK}} auth mediator server for this.** In return, the customer must provide a client ID and client secret for us to configure. ** In case of OIDC, the customer can decide which scopes/claims should be delivered with external systems the token and whether they want to use the ID token or the access token for authentication. * In the {{UBIK}} client profile, the SSO relevant settings must be adjusted (interfacingenabling SSO, specifying the protocol, the IdP URL, client ID, client secret, scopes and whether to use the access token).* On the server side, make sure that an SSO Processor is configured able to process the responses from the IdP. Also, the processor can be customized for managing the login in greater detail and according to the project's requirements.
In order to configure {{UBIK}} for SSO integration, we need to address both. == Authentication ==* In the {{UBIK}} client profile, adjust the SSO relevant settings (enabling SSO and specifying the Identity Provider Endpoint URL for an IdP-initiated flow).* On the server side, make sure that an SSO Processor is configured able to process the responses from the Identity Provider. == Authorization Interfacing ==When a {{UBIK}} object is synchronized between client and server, the {{UBIK}} customizing can interact with external systems. There, we might require authorization, and we need the user to make sure the client provides provide a respective tokenso we can act on their behalf. In order to do so, we have to identify the specific authorization use-cases:
* For which types of objects (meta classes) do I need to interact with external systems, requiring SSO authorization?
* For which synchronization operations (e.g., update, commit, create, etc.) do I need authorization?
* Which SSO client configurations (identity provider base URL, scopes, etc.- see "login") are used in this case?
For each resulting combination we have to create an [[SYSCLS_EXTERNALAUTHCONFIG|External Auth Config]] object and give it to the client in the infrastructure list.
Further, we have to make sure the authorization tokens can be transported to the server. Therefore, add the [[SYSCLS_EXTERNALENTITY|External Entity Classification]] to all meta classes of objects that need external authorization.
= Studio =
<!-- DO NOT MODIFY THE NAME OF THIS SECTION, BUT REMOVE IT IF NOT REQUIRED -->
== Authentication Login ==
* Install the Auth Processor plugin (SAMLProcessor or OIDCProcessor plugin) in your web service's injection folder
* Customize your UBIK Context, overriding the method "GetSSOProcessor" so it returns an instance of the authentication processor:
'''OIDC:'''
</syntaxhighlight>
Instead of "..." you will need to insert the correct URL from your OIDC Provider where the JWKS should originate from.
If the JWKS does not roll periodically:
</syntaxhighlight>
You will need to insert the correct jwks from your OIDC Provider instead of "...".
'''SAML:'''
You will need to load the correct certificate from your SAML Identity Provider instead of null. It's recommended to save the certificate on the server and load it from file storage. The certificate must be the one the IdP uses to sign its SAML responses with.
== Authorization Customizing the SSO processor == There are several use-cases where we need to customize the SSO processor. We can define what should be done when a login object is required or found, and we can use the information delivered with the SSO token in the form of assertions or claims. In any case, we must override the SSO processor implementation, e.g.: <syntaxhighlight lang="csharp">public class MyOIDCProcessor : DynamicOIDCProcessorExt{ // Example for a claim type identifier used to get a value from the Assertions() dictionary. public const string KEY_MAIL = @"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"; public MyOIDCProcessor(UBIKEnvironment environment, string token, string authorityBaseUrl) : base(environment, token, authorityBaseUrl) { } protected override Login CreateLogin(string loginName, string domain, OSTypes osType) { // In this example, we use the default login creation, but add the email address as the human-readable login name. // However, we could also use a special MetaClass for creating the login instance or do anything else we require. Login login = base.CreateLogin(loginName, domain, osType); // The Assertions() method yields a Dictionary<string, object>, where the values usually are strings, too. // The keys correspond to the claim type identifiers. if (Assertions().ContainsKey(Settings.KEY_MAIL) && !string.IsNullOrEmpty(Assertions()[KEY_MAIL] as string)) { login.Name = Assertions()[Settings.KEY_MAIL] as string; UBIKKernel.LogCustomizing(MethodBase.GetCurrentMethod(), $"Login name for {login.ID} was set to {login.Name} -> Key: {KEY_MAIL}"); } return login; } public override string GetLoginID() { // Here, we could influence the login ID used in UBIK, if we have a good mapping. return base.GetLoginID(); } public override Login GetLogin(UBIK.Service.DTO.V220.OSTypes osType) { Login login = base.GetLogin(osType); if (login == null) { // Here, we could update groups assignment or other account information. } return login; } public override bool IsValid() { // Here, we could only accept trusted accounts, for example. return base.IsValid(); }}</syntaxhighlight> == Interfacing ==
* Add [[SYSCLS_EXTERNALAUTHCONFIG|External Auth Config]] objects to the client's infrastructure
* Add the [[SYSCLS_EXTERNALENTITY|External Entity Classification]] to all affected meta class scopes
An external auth config object specifies for which meta class and sync action (e.g., when uploading instruction documents), which SSO configuration should be used. The result of a correct configuration will be, that the client sends an SSO token to the server when performing the sync action for an instance of the meta class. On the server side, you can use that token to interact with the external system. This only works if there is a scope with the external entity classification for that meta class, because it provides the means to transport the token.
[[Category:How-To|Integrate UBIK in an SSO Environment]]
[[Category:SSO|Integrate UBIK in an SSO Environment]]
[[Category:Version 3.6|Integrate UBIK in an SSO Environment]]
= Client =
<!-- DO NOT MODIFY THE NAME OF THIS SECTION, BUT REMOVE IT IF NOT REQUIRED -->
== OIDC ==
</InternalSSOSettings>
</syntaxhighlight>
== SAML ==
* Set up an identity provider if necessary