Skip to content

Drupal Identity Provider Overview and Setup

Jump to bottom
Kai edited this page Dec 20, 2021 · 20 revisions

Introduction

MDM uses a Drupal Identity Provider to authenticate and authorize users (via OAuth2 and OpenID Connect).

The Drupal Identity Provider also provides a User API which MDM will use to search for users when necessary (e.g. sending out emails to said users and updating if a user wants the welcome dialog should be shown or not).

NOTE: Throughout this WIKI you will see certain variables referenced. They are:

  • {IDP_SERVER} which refers to the root URL that the identity provider is running on
  • {IDP_PORT} which refers to the port the identity provider is acessible on
  • {MDM_SERVER} which refers to the root URL that MDM is running on
  • {MDM_PORT} which refers to the port on which MDM is accessible on.

Using docker-compose to Setup the Identity Provider

MDM provides the necessary Dockerfile and docker-compose.yml files to start the Identity Provider with little additional configuration necessary. You will still need to add the "resource server" and "task user" users as well as any users you wish to have access to MDM. When starting the identity provider with docker-compose up, the people/users administration path is http://localhost:8082/admin/people

Just download the MDM git repository, navigate to it in a terminal, and run docker-compose up if it is your first time starting the Identity Provider or docker-compose start any time after that.

The identity provider will then be, by default, accessible on http://localhost:8082.

Setup

It is recommended that you use the Docker images and docker-compose to setup the Identity Provider since almost all configuration is already complete.

If this is not possible, you will need to setup and configure a few things.

Drupal Setup

  1. Download and install Drupal on your server/local machine. Drupal can be downloaded here
  2. Download and add the Consumers extension. It can be downloaded here
  3. Download and add the OpenAPI extension. It can be downloaded here
  4. Download and add the Simple OAuth & OpenID Connect extension. It can be downloaded here
  5. Download and add the Simple OAuth Claims. It can be downloaded here

Identity Provider Setup

In order to setup the Identity Provider you will need to do the following:

  1. Add the clients/consumers (two are recommended one for the frontend, one for the report task). The client/consumer administration path is {IDP_SERVER}:{IDP_PORT}/admin/config/services/consumer OAuth2 Clients MDM Frontend Client Report Task Client
  2. Add a "resource server" user with the Administrator role. (MDM will use this user to make API calls to Identity Provider). The people/users administration path is {IDP_SERVER}:{IDP_PORT}/admin/people Users
  3. Update the JSON:API Settings to "Accept all JSON:API create, read, update, and delete operations." (this allows for resource server to update the users). The JSON:API administration path is {IDP_SERVER}:{IDP_PORT}/admin/config/services/jsonapi
  4. Add the MDM roles to Identity Provider. The roles administration path is {IDP_SERVER}:{IDP_PORT}/admin/people/roles. The following roles are needed:
    • ROLE_ADMIN
    • ROLE_USER
    • ROLE_PUBLISHER
    • ROLE_ANONYMOUS
    • ROLE_DATA_PROVIDER
    • ROLE_RELEASE_MANAGER
    • ROLE_TASK_USER Users
  5. Add a "task report" user with the ROLE_TASK_USER role (This user will be used by the Report Task CLI tool). The people/users administration path is {IDP_SERVER}:{IDP_PORT}/admin/people.
  6. (Optional) Add any extra languages you like. (NOTE: MDM currently only supports Germany and English.) The language administration path is {IDP_SERVER}:{IDP_PORT}/admin/config/regional/language
  7. Add all users who you would like to have access to MDM with their appropriate roles. The people/users administration path is {IDP_SERVER}:{IDP_PORT}/admin/people.

MDM Setup

In order for MDM to know about the Identity Provider the following environmental endpoints will need to be set:

  • RESOURCE_SERVER_ISSUER_URI: The root URL to the Identity Provider. NOTE: "/.well-known/openid-configuration" will be added to the provided URI in order to configure the OAuth2 and OpenID Connect settings. This should usually be set to {IDP_SERVER}:{IDP_PORT} but may also need an additional path if the Identity Provider is not running on the root index of the specified server/port. For example, http://example.com:1234/identity-provider.
  • USER_API_ENDPOINT: The root URL to the User API endpoint. NOTE: MDM adds "/jsonapi/user/user" to the URI whenever it makes requests to the Identiy Provider User API endpoints. This should usually be set to {IDP_SERVER}:{IDP_PORT} but may also need an additional path if the Identity Provider is not running on the root index of the specified server/port. For example, http://example.com:1234/identity-provider.
  • USER_API_USERNAME: The username of the "resource server" you created in the Identity Provider setup.
  • USER_API_PASSWORD: The password of the "resource server" you created in the Identity Provider setup.

Client Build

The client build expects the following environment variables in order to configure the client for using the identity provider:

  • local: CLIENT_ID_LOCAL, CLIENT_SECRET_LOCAL, ISSUER_LOCAL
  • dev: CLIENT_ID_DEV, CLIENT_SECRET_DEV, ISSUER_DEV
  • test: CLIENT_ID_TEST, CLIENT_SECRET_TEST, ISSUER_TEST
  • prod: CLIENT_ID_PROD, CLIENT_SECRET_PROD, ISSUER_PROD

The builds are executed with grunt buildlocal for instance.

Run locally

Due to the same origin policy it is recommended to disable the web security (flag: --disable-web-security) on your chrome/chromium browser.

User API

MDM also has a User API which can be used to search for and update users in the Identity Provider. You can read the Swagger Documentation for this API under the URL {MDM_SERVER}:{MDM_PORT}/api/swagger-ui/index.html#/user-resource

Report Task Command Line tool

The Report Task Command Line tool is a CLI application which handles the necessary requests to MDM, PDF compiliation, and upload logic needed to add a report to MDM.

For a complete overview of the Report Task CLI tool, please read its README.md here

Setup

The Report CLI tool requires the following setup before it can run successfully:

Basic Setup

The following environmental variables need to be added:

  • MDM_ENDPOINT: The URL which points to the root of MDM. If you used the docker-compose -f docker-compose-app.yml command this should be set to http://localhost:8080

Authenticating and Authorizing Setup

The "Report Task" CLI tool needs the following environmental variables to authenticate and authorize requests:

  • FDZ_ISSUER_URI: The URI to the Drupal Identity Provider where your user is stored. If you used the docker-compose command this should be set to http://localhost:8082
  • FDZ_CLIENT_ID: The ID of the Client/Consumer with which will be used to authenticate and authorize the requests Report Task needs to make
  • FDZ_CLIENT_SECRET: The Secret of the Client/Consumer with which will be used to authenticate and authorize the requests Report Task needs to make

NOTE: It is assumed that your Drupal Identity Provider is completely configured.

Wiki Home

Product Vision

Developer Docs

User Docs

Clone this wiki locally