OpenID Connect
Introduction
The OpenID Connect protocol is the successor to the OpenID protocol for federated identity. It is an extension of the OAuth protocol.
Modules
The core OpenID Connect protocol is implemented in the SimpleID\Protocols\Connect\ConnectModule
module.
This module is enabled by default.
The OpenID Connect module automatically enables the required OAuth modules for its operation.
Additional modules related to the OpenID protocol are set out in the table below.
Module | Description | Enabled by default? |
---|---|---|
SimpleID\Protocols\Connect\ConnectClientRegistrationModule | Implements OpenID Connect dynamic client registration | No |
SimpleID\Protocols\Connect\ConnectSessionModule | Implements OpenID Connect session management | No |
User configuration
User information
One of the objectives of the OpenID Connect protocol is to supply information about the user to
the requesting app or web site. Therefore the protocol is only useful if you store your user
information under the userinfo
object in the user file. For example, you can store your
name and e-mail address as follows:
userinfo:
name: "Jane Citizen"
email: "jane@example.net"
WebFinger
In order for apps and web sites to discover your SimpleID installation, you will need to set up WebFinger. The SimpleID distribution includes a simple WebFinger server. See the WebFinger page for further information on how to set this up.
Alternatively, if you wish to run your own WebFinger server, you will need to point
the relationship http://openid.net/specs/connect/1.0/issuer
for each user to your SimpleID server.
Client configuration
Clients can be registered with SimpleID manually or through the OpenID Connect Dynamic Registration protocol (if this is enabled).
Registering a client manually
To register a client manually, create a client file for the client using the instructions set out in Setting up clients.
The OpenID Connection configuration is specified under the oauth
and connect
objects in the client file. At a minimum, at least one redirect URI must be specified in oauth.redirect_uris
.
oauth:
redirect_uris:
- https://example.com/oauth/redirect
See example.client.yml
in the identities directory for further details of the configuration options.
In addition to registering the client, the client itself needs to be configured to use SimpleID as the server.
OpenID Connect Dynamic Registration
Alternatively, if the client is supports the OpenID Connect Dynamic Registration and the SimpleID\Protocols\Connect\ConnectClientRegistrationModule
module is enabled, then the client can register itself as part of the discovery process.
Endpoint configuration
In addition to registering the client with SimpleID, each client also needs to be configured to use SimpleID as the OpenID Connect endpoints. This configuration may occur automatically through OpenID Connect Discovery or you may need to configure the client manually.
OpenID Connect Discovery
If the client supports OpenID Connect Discovery, then it will be able to query the /.well-known/openid-configuration
endpoint to retrieve the relevant configuration.
Clients using WebFinger should support OpenID Connect Discovery. Alternatively, the client may allow you to specify the domain name or the OpenID Connect Discovery endpoint.
You need to make sure that the web server is correctly configured to point the /.well-known/openid-configuration
to SimpleID. See the installation instructions for further details.
Manual configuration
To manually configure a client, specify the following endpoints, with the URL of the SimpleID installation prepended:
Endpoint | URI |
---|---|
Authorisation endpoint | /oauth/auth |
Token endpoint | /oauth/token |
UserInfo endpoint | /connect/userinfo |