An OpenID Connect Button to instrument Web pages with OpenID Connect authentication and access to user information using an external OpenID Connect Provider via the OpenID Connect implicit flow.
Table of Contents
Try it --TODO: add link to working online demo.
Developer Tutorial == This tutorial provides step-by-step instructions on how to instrument an arbitrary Web page client with the OpenID Connect Button to enable authentication and access to user information. The button is automatically rendered based on a couple of attributes that define OpenID Connect-relevant configuration details. Developers receive access to different OpenID Connect related information such as provider configuration, tokens, and user information. When users of a client sign in with an OpenID Connect provider, the client gets an *access token*, which can be further used to make calls to service APIs capable of interacting with the OpenID Connect provider. Add the OpenID Connect Button to a Web page -- Adding the OpenID Connect button to a Web page client is done in four simple steps:- Step 1: Register page as OpenID Connect client.
- Step 2: Include OpenID Connect Button script on client page.
- Step 3: Add HTML element representing button to the client page.
- Step 4: Handle sign in with JavaScript callback.
OpenID Connect client registration frontends look different on different server implementations. In this section, we walk you through the dialogs provided by the Open Source MITREid Connect Server version 1.1.8.
- Log in to the OpenID Connect server (register for an account, if necessary).
- In the Developer section in the menu on the left choose Self-service client registration.
- Click the button Register a new client.
- A page New Client with six tabs Main, Access, Credentials, Crypto, Other, and JSON will open. In the next steps, configure your client on each of the tabs. Be sure to press Save after completing every tab!
- Tab Main 1. enter an arbitrary Client name 1. paste the deploy URL of your client page as Redirect URI and click the "+" button 1. optionally fill in all other fields
- Tab Access 1. for Grant Types choose implicit 1. for Response Types check fields token, id_token, and token id_token (uncheck all other boxes)
- Tab Credentials: keep Token Endpoint Authentication Method on Client Secret over HTTP Basic
- Tab Crypto: leave all fields on Use server default
- Tab Other: nothing to do here for now
- Tab JSON: shows a JSON representation of your client configuration
- Go back to tab Main and copy values for Client ID and Registration Access Token.
- Store values for Client ID and Registration Access Token in a safe place! You will need them for using the OpenID Connect Button and for any re-configuration of your OpenID Connect client!
- In case you have to re-configure your client, select Self-service client registration from the Developer section in the menu on the left, enter Client ID and Registration Access Token in the fields on the right and click the button Edit an existing client. If you are an administrator of the OpenID Connect server, you can make use of the menu entry Manage Clients in the Administrative section in the menu on the left.
Include the following script just before the closing body tag:
<!-- Place this asynchronous JavaScript just before your </body> tag -->
<script type="text/javascript">
(function() {
var po = document.createElement('script');
po.type = 'text/javascript';
po.async = true;
po.src = './oidc-button.js';
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(po, s);
})();
</script>The OpenID Connect Button script depends on jQuery, bootstrap, jsjws, and jsrsasign. Be sure to include all required dependencies to JS and CSS, as demonstrated in index.html.
Include a HTML element that represents the OpenID Connect Button. The script included in the previous step will transform the element into a button appearance. Use the client ID you retrieved from step 1.
<span class="oidc-signin"
data-callback="signinCallback"
data-name="Learning Layers"
data-logo="http://learning-layers.eu/wp-content/themes/learninglayers/images/logo.png"
data-server="https://api.learning-layers.eu/o/oauth2"
data-clientid="CLIENTID"
data-scope="openid phone email address profile">
</span>The HTML element must define the following data attributes:
| Attribute Name | Description |
|---|---|
| data-name | Name of the OpenID Connect Provider |
| data-logo | URL of an OpenID Connect Provider logo (ideally 32px high SVG/PNG with transparent background) |
| data-size | Display size of the button ('xs': extrasmall, 'sm': small, 'default': default, 'lg': large) |
| data-server | URL of the OpenID Connect Provider server |
| data-clientid | OpenID Connect client ID as retrieved in Step 1 |
| data-scope | Space-separated OpenID Connect scopes. The standard scope is simply "openid", but other scopes are usually also available (e.g. email, address, profile). A full list of scopes supported by the OpenID Connect provider is available via OpenID Connect discovery of provider configuration (see below for more information) |
| data-callback | Name of a callback function defined in a script tag of the client page handling the outcome of the sign in process done by the button (see next step). |
In a script of your client page define a JavaScript function that is triggered after the OpenID Connect Button is loaded. The name of the function must match the value of the data-callback attribute of the HTML element defined in Step 3. The function is passed an object that represents the authorization result.
When sign in is successful, the result simply contains the string "success". At this point, you have access to the following variables representing OpenID Connect-related information:
| Variable Name | Description |
|---|---|
| oidc_server | OpenID Connect Provider server URL |
| oidc_name | OpenID Connect Provider name |
| oidc_logo | OpenID Connect Provider logo URL |
| oidc_clientid | OpenID Connect client ID |
| oidc_scope | OpenID Connect scope |
| oidc_provider_config | OpenID Connect Provider configuration as retrieved via OpenID Connect Discovery |
| oidc_userinfo | OpenID Connect user info claim as retrieved from the OpenID Connect User Info endpoint. |
| oidc_idtoken | OpenID Connect ID token including parsed payload (cf. OpenID Connect Core) |
| If the user is not signed-in, the result represents the respective error message describing the cause of the failed sign in. Causes include authentication errors, denial of access to user information expressed by user in OpenID Connect consent dialog, invalid tokens, etc. |
The following example of a callback function greets the signed in user with a welcome message displayed in an HTML element with id "status" in case sign in succeeded and in case of an error logs the cause on the console.
function signinCallback(result) {
if(result === "success"){
// after successful sign in, display a welcome string for the user
$("#status").html("Hello, " + oidc_userinfo.name + "!");
} else {
// if sign in was not successful, log the cause of the error on the console
console.log(result);
}
}
<a name="license"/>The OpenID Connect Button is released under the BSD license by Dominik Renzel, Advanced Community Information Systems (ACIS) Group, RWTH Aachen University, Germany.
Framework plugins == Meteor (web framework) -- For the meteor web framework you can add the Learning Layers OpenID Connect Button via ```meteor add aur0r:accounts-learninglayers```. You can find the plugin in AtmosphereJS at [https://atmospherejs.com/aur0r/accounts-learninglayers](https://atmospherejs.com/aur0r/accounts-learninglayers). License: MIT.