Identity Provider Broking¶

An Identity Broker is an intermediary service connecting service providers with identity providers. The identity broker creates a relationship with an external identity provider to use the provider’s identities to access the internal services the service provider exposes.

From a user perspective, identity brokers provide a user-centric, centralized way to manage identities for security domains and realms.

Typically, Keycloak bases identity providers on the following protocols:

SAML v2.0
OpenID Connect v1.0
OAuth v2.0

The following page will describe the needed configurations in order to have AzureID (or any 3^rd party identity provider) as identity provider for our IAM (Keycloak based) service. This includes the creation of an application integration, as well as its configuration. Both OIDC and SAML integrations are covered. Based on expert guidance, OIDC was chosen for IAM.

Create Azure Application¶

Go to the Azure Portal.
Sign in with your Azure account credentials.

Register a New Application¶

In the Azure portal, search for App registrations in the search bar.
Click on New registration.
Fill in the required details:

a. Application Name: Enter a name that uniquely identifies that app within GridLab AG and also relates to the main purpose of the app. For apps with multiple application lines, we recommend to include the application line as a postfix (such as, "- DEV" "- QA"), while keeping the rest of the name equal. This will allow easier identification of related apps.

PSSX-Keycloak-OIDC-DEV / PSSX-AuthServer-OIDC-DEV / PSSX-AuthServer-OIDC-STAGE

b. Supported account types: Choose who can use the application (e.g., single tenant, multi-tenant, or personal Microsoft accounts).

c. Click Register to create the application.

OIDC Integration¶

Select your newly created app from Azure AD Portal - App Registration List

Select Authentication in the Manage section on the left pane.
Select Add a platform
On the Configure platforms window, select the appropriate platform

Choose platform type Web when: your app's documenation asks for setting a client secret

Flow: authentication code flow with client secret
Typically used by: browser app with a backend

Choose platform type Single-Page Application (SPA) when: Your app is an SPA, running only in a browser

Flow: authentication code flow without client secret (and PKCE + CORS protection)
Typically used by: browser app with frontend only

Web Application¶

You need to configure Redirect URIs, The URIs we will accept as destinations when returning authentication responses (tokens) after successfully authenticating or signing out users.

http://localhost:8080/realms/master/broker/oidc/endpoint / https://locahost:43342

You need to configure Front-channel logout URL.

Leave it empty

Select the tokens required.

ID tokens (used for implicit and hybrid flows)

Note : OIDC gives you an access token plus an ID token, which you can send to an application to prove your identity. The ID token is a JSON Web Token (JWT) and contains information about the authenticated user. The identity provider (Microsoft Identity platform) signs the token, so that application can verify the authentication by using the provider's public key.

SPA Application¶

You need to configure Redirect URIs, For details on this procedure, refer to Register single-page applications (SPA) - Microsoft identity platform | Microsoft Docs.

Certificates and secrets¶

You can add both certificates and client secrets (a string) as credentials to your app registration

Select Certificates & secrets in the Manage section on the left pane.
To add a client secret, go to the Client secrets tab and select + New client secret.
To add a certificate, go to the Certificates tab and select Upload certificate.

Client secret is 7On8Q~-IG / zHs8Q~eO / SLc8Q~ET

Where to find information on endpoints (e.g, well-known endpoint)? What is the issuer?¶

In order to configure the application side, you need information about the endpoints

If you have a single-page application (strictly recommended, unless required otherwise), the following standard values will app :

Well-known endpoint: https://login.microsoftonline.com/38ae3bcd-9579-4fd4-adda-b42e1495d55a/v2.0/.well-known/openid-configuration

You can request admin consent for the OIDC permissions (openid, profile, email, offline_access) and User.

Following the OIDC / Outh2 Integration steps, certain important attributes need to be set;

OpenID Connect settings:

Advanced settings:

Following the OIDC / Outh2 Integration steps must be taken;

Appsettings:

Ensure that you have been added https://login.microsoftonline.com value to the CORS settings

"App": {
    "CorsOrigins": "https://*.pssx.cloud,http://localhost:4200,https://localhost:44377,https://localhost:44322,https://localhost:44338,https://localhost:44366,https://login.microsoftonline.com",
},

"AzureAd": {
    "Authority": "https://login.microsoftonline.com",
    "MetadataAddress": "https://login.microsoftonline.com",
    "TenantId": "38ae3bcd-9579-4fd4-adda-b42e1495d55a"
},

Configure authentication in PSSXAuthServerModule.cs at GridLab.PSSX.AuthServer project:

context.Services.AddAuthentication()
    .AddAbpOpenIdConnect("GridLab AD", "GridLab AD", options =>
    {
        options.Authority = configuration["AzureAd:Authority"].EnsureEndsWith('/') + configuration["AzureAd:TenantId"].EnsureEndsWith('/') + "v2.0".TrimEnd('/');
        options.MetadataAddress = configuration["AzureAd:MetadataAddress"].EnsureEndsWith('/') + configuration["AzureAd:TenantId"].EnsureEndsWith('/') + "v2.0".EnsureEndsWith('/') + ".well-known/openid-configuration";
        options.ResponseType = OpenIdConnectResponseType.CodeIdToken;

        options.UsePkce = true;
        options.GetClaimsFromUserInfoEndpoint = true;

        options.TokenValidationParameters = new TokenValidationParameters()
        {
            ValidateAudience = false,
            ValidateIssuer = true,
        };

        options.TokenValidationParameters.ValidIssuers = new[]
        {
            configuration["AzureAd:Authority"].EnsureEndsWith('/') + configuration["AzureAd:TenantId"].EnsureEndsWith('/') + "v2.0".TrimEnd('/'),
            configuration["AzureAd:MetadataAddress"].EnsureEndsWith('/') + configuration["AzureAd:TenantId"].EnsureEndsWith('/') + "v2.0".TrimEnd('/')
        };

        options.Scope.Add("openid");
        options.Scope.Add("profile");
        options.Scope.Add("offline_access");
        options.Scope.Add("email");
    });

Configure ConfigureExternalProviders method in PSSXHttpApiHostModule.cs at GridLab.PSSX.HttpApi.Host:

context.Services
    .AddDynamicExternalLoginProviderOptions<GoogleOptions>(
        GoogleDefaults.AuthenticationScheme,
        options =>
        {
            options.WithProperty(x => x.ClientId);
            options.WithProperty(x => x.ClientSecret, isSecret: true);
        }
    )
    .AddDynamicExternalLoginProviderOptions<MicrosoftAccountOptions>(
        MicrosoftAccountDefaults.AuthenticationScheme,
        options =>
        {
            options.WithProperty(x => x.ClientId);
            options.WithProperty(x => x.ClientSecret, isSecret: true);
        }
    )
    .AddDynamicExternalLoginProviderOptions<TwitterOptions>(
        TwitterDefaults.AuthenticationScheme,
        options =>
        {
            options.WithProperty(x => x.ConsumerKey);
            options.WithProperty(x => x.ConsumerSecret, isSecret: true);
        }
    ).AddDynamicExternalLoginProviderOptions<OpenIdConnectOptions>(
        "GridLab AD",
        options =>
        {
            options.WithProperty(x => x.ClientId);
            options.WithProperty(x => x.ClientSecret, isSecret: true);
        }
    );

SAML Integration¶

After you have created an application integration, you can access its enterprise application (= service principal) by going to the Enterprise applications blade in Azure AD Portal and click on your app's name.

On the Getting Started / Overview page, select Set up single sign on. (alternatively select Single sign-on from the menu on the left-hand side)
Select SAML to open the SSO configuration page.

The process for configuring an application to use Azure AD for SAML-based SSO varies depending on the application

Set up Single Sign-On with SAML¶

In the Basic SAML Configuration section, select the Edit icon.
Update the Identifier (Entity ID), The unique ID that identifies your application to Azure Active Directory. This value must be unique across all applications in your Azure Active Directory tenant. The default identifier will be the audience of the SAML response for IDP-initiated SSO.

http://localhost:8080/realms/master

Update the Reply URL, The reply URL is where the application expects to receive the authentication token. This is also referred to as the “Assertion Consumer Service” (ACS) in SAML.

http://localhost:8080/realms/master/broker/saml/endpoint

Select Save

Attributes & Claims¶

In the Attributes & Claims section, select the Edit icon to edit the configuration.
Configure the NameID, as well as Attributes, according to your application's needs.
Select Add new claim to open the Manage user claims page.
Enter the claim name which your application should receive.

Name: gid, Namespace: http://schemas.xmlsoap.org/ws/2005/05/identity/claims

In the Source field, select Attribute.
In the Source attribute field, enter extension_gid.

How can I control which users can authenticate to my application?¶

Find more details and options how to change this in the following manual: How to configure which users and groups can authenticate to your Azure AD application.

In the Manage section of the left menu, select Users and groups.
Select +Add user/group and in the Users and groups dialog box, select the group that you wish to add.
Click the Select button at the bottom of the screen.

Where to find SAML Metadata Url ?¶

In the SAML Certificates section, copy App Federation Metadata Url value, you can also download metadata from Federation Metadata XML link.

Following the SAML Integration steps, certain important attributes need to be set;

SAML settings: