ID Broker operations manual

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.

  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.

On this page