How to integrate your login page
Enterprises can enjoy branded and fully customised login / consent pages with the Connect2id server.
This is enabled by a powerful web API which facilitates binding of arbitrary UIs to the OAuth 2.0 authorisation endpoint of the server. The login page can be built with any language and framework. Businesses can have multiple tailored logins for different audiences (e.g. corporate vs consumer users) or devices (PC vs mobile). The login page can be hosted independently from the Connect2id server, leveraging HA proxies and CDN if needed.
The role of the login page
The login page must intercept HTTP requests directed at the OAuth 2.0 authorisation endpoint. This is the place where client applications redirect the browsers of end-users to authenticate with the Connect2id server (as an OpenID Connect provider) and state their intent to allow the client app to receive access to personal identity details that have been asked for, or other OAuth 2.0 access-token protected data / web APIs.
Registering the login page
The Connect2id server must know the URL of the login page. This is done by setting the op.authz.endpoint configuration parameter.
The server will then advertise the login page location as its OAuth 2.0 authorisation endpoint described above. This happens through the OpenID Connect provider metadata, which is published at a well-known location as a JSON object.
https://[base-server-url]/.well-known/openid-configuration
Authentication / consent flow
Upon receiving an OpenID Connect authentication request the login page must perform the following steps:
Step 1.
Extract the query string and the session cookie (if present) from the HTTP request. Then use the these two parameters to make a POST request to start a new authorisation session. That's basically a set of interactions to establish the end-user's identity and get their consent.
Step 2.
The Connect2id server will create an authorisation session, and return its
identifier, or sid, in the response (not to be confused with the browser
session established with the cookie).
Step 3.
If the POST response prompts for authentication this can mean two things:
The user has no session with the Connect2id server;
The authentication strength, or level, (ACR) needs to be upgraded to match the application's security requirement.
For the simple case (1), create an HTML form, get the user's credentials and verify them (using whatever mean you have to, such as a call to your Active Directory / LDAP server).
On success do a PUT to
the authorisation session ID (sid) with the end-user authentication
details. With that the identity of
the end-user has been established, and the Connect2id server will create an
internal session for the user.
Proceed to step 5.
Step 4.
If the POST response is a consent prompt this means that the end-user has a valid session with the Connect2id server, and the authentication strength is fine too.
Proceed to step 5.
Step 5.
Gather / compose the authorisation, by presenting a credentials form to the end-user, or by some other mean. When you're done do a PUT with the consent. The response will be an HTTP 302 redirection, which you can then use to send the browser back to the client app.
Step 6.
If you get an HTTP 302 response at any other time, use the Location header
to redirect the browser back to the client app.
Step 7.
If you get a 220 response at any time this means some kind of an authorisation error has occurred, but the browser must NOT be redirected.
Step 8.
If the user chooses not to authorise the client app, do a DELETE and handle the redirection as described above.
Example login page
The Connect2id server comes with an example login page which is built with JavaScript and demonstrates the typical logic and RESTful requests that go into it.
https://bitbucket.org/connect2id/connect2id-login-page-js
Important: The login page is implemented in browser JavaScript, and must therefore only be used for testing and development purposes. Production login pages must use server-side code to implement the business logic and the web API calls to the Connect2id server.