How to integrate your login page
Enterprises can enjoy a branded and fully customised login / consent experience with the Connect2id server.
This is facilitated by a powerful web API for binding arbitrary UIs to the OAuth 2.0 authorisation endpoint of the server. Any language / framework can be utilised for that, leveraging your existing development resources and experience. Enterprises can operate multiple logins tailored for each target audience (e.g. corporate vs consumer users) or device (PC vs mobile). The login UI can be hosted independently from the Connect2id server, employing HA proxies and CDN if needed.
The job of the login page
The job of the login page is to intercept HTTP requests directed at the OAuth 2.0 authorisation endpoint. This is the URL where client applications send the end-user's browser to perform the following tasks:
Authenticate the end-user with the Connect2id server (in its role as an OpenID Connect identity provider);
Let the end-user allow / deny the client app access to requested personal details (UserInfo), or other protected data / web APIs secured by the Connect2id server (in its role an OAuth 2.0 authorisation server).
Registering the login page
The login page URL must be saved in the op.authz.endpoint configuration property of the server.
Them Connect2id server will then advertise the login page location as its OAuth 2.0 authorisation endpoint, as 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 one is present) from the HTTP request. Then use the these two parameters to make a POST request to start a new authorisation session. This session is basically a set of interactions to establish the end-user's identity and ask for 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 at step 2 prompts for authentication this can have two meanings:
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, then 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 will have been established, and the Connect2id server will create
an internal session for the user.
Proceed to step 5.
Step 4.
If the POST response at step 2 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 all web API calls to the Connect2id server.