Service providers

4. Service providers#

4.1. Service provider mapping and secrets#

The ID broker requires a special UDM property and a secret for each service provider. You have to use the tool manage-service-providers to register a new service provider. For each service provider you have to specify a short name. The tool allocates a free UDM property and generates a secret. Both values are automatically assigned to the short name.

  • To add initial service providers use the tool manage-service-providers. You have to specify a short name for each service provider. In the following command line examples, $SP_NAME refers to the short name. It has to be unique and must not contain any space or tabulator characters.

    $ manage-service-providers addservice --name $SP_NAME

    The tool iterates over all existing users, groups and school OUs and generates a pseudonym. Service providers can use the pseudonym. Depending on the number of objects in the LDAP directory, this might take some time.

  • To rerun the addition of a service provider, even if that provider already exists, you can use the --overwrite flag. Please be advised, that this regenerates the service specific pseudonyms for all objects, which might change them. This flag is useful if a previous creation of a service provider aborted and you want to restart the process.

    $ manage-service-providers addservice --name $SP_NAME --overwrite

  • To get the name of the UDM property of a specific service provider, call:

    $ manage-service-providers showsetting mappings --key $SP_NAME

  • A secret salt is used to create the pseudonyms. Never share this secret to avoid compromising the pseudonyms. To get the salt of a given service provider, call:

    $ manage-service-providers showsetting secrets --key $SP_NAME

When omitting the parameter --key, the output shows the mappings or secrets of all service providers:

root@backup:~# manage-service-providers showsetting mappings
{
    "coolServiceProvider": "idBrokerPseudonym0002",
    "univention-test-app": "idBrokerPseudonym0001"
}

The output shows all defined service provider short names and the corresponding mapping to a UDM property. Please note that when adding a new service provider you need the short name of your new service provider and the corresponding UDM property name later on for the configuration of Keycloak. Therefore, keep these two values at hand.

4.2. Registration of a new service provider#

Service providers who want to use the ID Broker, must provide a service configured for single sign-on with the ID Broker. Service providers must first register within the ID Broker. To start the registration, the service provider must contact you as the operator of the ID Broker and ask you to register its service.

  1. Create a new service provider in LDAP and determine the UDM property used for this specific service provider (for example idBrokerPseudonym0001). For details about both steps, see Service provider mapping and secrets. In a step below the UDM property name has to be filled in to a configuration file.

  2. You get a redirect URL along with its registration request from the service provider. The ID broker (Keycloak) redirects the user’s browser to this URL, once the login to the ID broker was successful. You need the redirect URL in your next step.

    Ask the service provider also for the URLs that its service uses as post_logout_redirect_uri for the sign-out. Keycloak validates the post_logout_redirect_uri against the redirect URIs of the client. Therefore, the list of redirect URIs must cover these URLs as well. For more information, see Single logout.

  3. Update clients.yml of the Keycloak Ansible playbook.

    Chapter Backup - SSO Service - Keycloak describes how to configure Keycloak through Ansible. Run the following steps in the file system folder keycloak on the Ansible system for each service provider you want to add. Edit clients.yml to include the service provider.

    The client_id is a public identifier for apps and service providers. It is best practice to use a random string. If the client ID is guessable, it lowers the barrier for phishing attacks against arbitrary applications. The client_id must be unique across all clients. As the operator of the ID Broker, you must generate the client_id and a new secure secret.

    Include the service provider name in the client_id. This makes it easier for you to identify clients within the Keycloak management interface. Use the following command to create a client_id:

    $ echo "$SP_NAME.$(makepasswd --chars=18)"

    Create a new secure OpenID client secret. This secret is shared with the service provider to create mutual trust between them and the ID Broker. Use the following command to create a secret:

    $ makepasswd --chars=32

    Replace the $CLIENTID, $CLIENTSECRET and UDMPROPERTY in the following example with the distinct values for client ID, secret and UDM property name. Also, replace $REDIRECT_URL_TO_CLIENT_APP with the URL provided by the service provider. Please note that the service provider can specify multiple URLs. In this case, you must enter all URLs in the file. See the clients.yml.example. For example:

    register_clients:
  - client_id: "$CLIENTID"
    secret: "$CLIENTSECRET"
    redirect_uris:
      - "$REDIRECT_URL_TO_CLIENT_APP"
    pseudonym_attr: "$UDMPROPERTY"

  4. Updating the Keycloak configuration

    To activate the new service provider in Keycloak, follow the steps in Backup - SSO Service - Keycloak. If you have already completed the installation of Keycloak and are just adding a new service provider, it is sufficient to run the Ansible playbook:

    $ ansible-playbook -i hosts.ini main.yml

  5. Adapt the system of the Self-disclosure API so it allows the service provider to access it.

  6. After you successfully configured Keycloak, send the client ID and the corresponding secret to the service provider. The service provider can then configure its service for the ID broker accordingly.

4.3. Service/App requirements#

The service provider’s app must support the OpenID Connect (OIDC) authentication protocol, more specifically the Authorization Code Flow. OIDC is an identity layer built on top of the OAuth 2.0 protocol.

In addition, the service provider’s app must use the Proof Key for Code Exchange (PKCE) protocol. Regarding OIDC and OAuth 2.0, see OAuth 2.0 Security Best Current Practice.

The ID broker publishes its OIDC metadata under the following Well-known-URI:

https://login.FQDN/auth/realms/ID-Broker/.well-known/openid-configuration

The URI returns a JSON list of OIDC endpoints, supported scopes and claims, public keys used to sign the tokens, and other details. The service provider application can use this information to create a request to the ID Broker (OIDC server) and validate the access_token.

4.4. Single logout#

The ID Broker signs a user out of the whole single sign-on session, if all of the following conditions apply:

  1. The service ends the session at the ID Broker.

    The service provider is responsible for this step. The service redirects the user’s browser to the end_session_endpoint of the ID Broker’s Keycloak and passes an id_token_hint, as described in OpenID Connect RP-Initiated Logout. A service that doesn’t do this only ends its own session.

  2. The client of the service allows the URL of its post_logout_redirect_uri.

    You configure this as the operator. Keycloak validates the post_logout_redirect_uri against the redirect URIs of the client. If the service passes a URL that the redirect URIs of its client don’t cover, Keycloak refuses the sign-out request. Ask the service provider for these URLs and add them to redirect_uris in clients.yml, as described in Registration of a new service provider.

  3. The ID Broker connects the school authority’s identity provider through OpenID Connect.

    You configure this as the operator, together with the school authority. The ID Broker only propagates the sign-out to identity providers that it connects through OpenID Connect. For identity providers that the ID Broker connects through SAML, the session at the school authority stays active. For more information, see Add a new school authority to Keycloak.

  4. The school authority signs in to its Portal and UMC with OpenID Connect.

    Otherwise the identity provider of the school authority doesn’t end the session of the Portal and of UMC. The school authority is responsible for this configuration. The ID Broker manual for school authorities describes the required steps.

On this page