OpenID Connect and O4W

OpenID Overview

OpenID was designed as an open protocol for single sign on solutions.  OpenID clients could redirect users to OpenID providers (such as Google, Yahoo, and many others) for authorization and login; the information returned after successful login could then be associated with an O4W user, or the information for a generic "OpenID user" could then be used for the current session.  Note: OpenID has been phased out, or is being phased out, in favor of OpenID Connect by many providers (such as Google).

OpenID Connect Overview

OpenID Connect (OIDC) is the latest framework designed to allow single sign on functionality across the internet.  OIDC Providers (such as Google, eBay, AOL, and others) are used to log in and validate users for OIDC clients (also called "Relying Parties").  O4W can act as an OIDC client, allowing developers and site administrators to specify one or more OIDC Providers that they wish to use.  If an end user selects to log in with one of the OIDC Providers, they will be prompted to log in (if not already logged in) to the OIDC Provider web site, and allow O4W (or another application name, if the developer/site administrator has specified one) access to their user information.

Normally, the developer/site administrator will register their application with the OIDC Provider(s) they wish to support; for example, to use "Login with Google+", the developer must visit Google's "Developers Console" and create a project (currently found at https://console.developers.google.com/project).  This is different than the previous version of OpenID, which did not require any "pre-registration"; OIDC requires either pre-registration (or, if the OIDC Provider supports it) dynamic registration, to enhance user security.

As mentioned, OIDC allows for several optional capabilities, which may or may not be supported by a particular OIDC Provider.  In addition to dynamic registration, OIDC defines the ability to dynamically resolve which provider should be used by the entry of the end user's email address, or the URL of the OIDC Provider.  Note that while O4W includes this functionality, at this time, most providers do not support it.

Setting up OpenID and OpenID Connect for O4W

Both OpenID and OIDC are configured via the CFG_OPENID record in SYSENV.  Developers/Site administrators can create an application- and user-specific version of this record, named CFG_OPENID*<appid>*<username> (for example, CFG_OPENID*MYAPP*SAMPLEUSER), or a user-specific version (CFG_OPENID**<username>), or an application-specific version (CFG_OPENID*<appid>), rather than using the global CFG_OPENID record, if desired.

Field 1 of the configuration record defines which version, if any, of OpenID is supported by O4W.  If field 1 is set to "0", then OpenID is not supported at all.  If field 1 is set to "1", then OpenID (the original implementation) is used.  If field 1 is set to "2", OpenID Connect (the current version) is used.

If either original OpenID or OpenID Connect is selected, additional fields must be completed to specify how O4W should use OpenID.

Field 2 is the name of the defined O4W user (created via the O4W User Maintenance form) that should be used when an OpenID or OpenID Connect user logs in, if they choose not to create their own O4W user.  This allows developers/system administrators to control the permissions level of OpenID/OIDC users.

Field 3 specifies the overall layout of the user interface.  If set to "0", then only the O4W login screen will be displayed; if set to "1", the O4W login screen will be displayed on the left hand side of the screen and the OpenID login screen will be displayed on the right hand side of the screen; if set to "2", the OpenID login screen will be on the left and the O4W screen will be on the right; and if set to "-1", then only the OpenID login screen will be displayed.

Field 4 is multivalued; value 1, if set to "1", indicates that O4W should attempt to match OpenID/OIDC users to O4W users.  Value 2, if set to "1", indicates that O4W should allow OpenID/OIDC users to create new O4W users when logging in.

Field 5 optionally specifies the name of the "matching" routine to use, if field 4 value 1 is set to "1".  This can be left blank for the default routine to be used.

Field 6 optionally contains the name of a record to create that will contain "debugging" information for the OpenID/OIDC session.  This is normally left blank.

Fields 10 through 24 only apply to OpenID Connect; they control both the user interface display, and the actual details, used for each connection.

The OIDC protocol allows for "dynamic selection" of OpenID Connect providers based on either URL or email address.  If developers/site administrators wish to allow the entry of URLs and/or email addresses (rather than restrict the use of OpenID Connect to specifically defined providers), they can enter the prompt text to display to their end users in field 10.  Leave this field blank to disallow "dynamic selection" (Note: at this time, most providers do not support "dynamic selection").

The OIDC protocol also allows for "dynamic registration" of OpenID Connect clients, such as O4W.  If developers/site administrators wish to allow for dynamic registration, they must set the value of field 11 to "1", and specify a name to use for their application in field 12.  (Note: at this time, many providers, such as Google, do not support dynamic registration).

If desired, an optional "stylesheet" can be specified in field 13; this will be included in the OpenID Connect user interface, and can be referenced in field 17.

For each OpenID Connect provider that the developer/site administrator wishes to explicitly allow, fields 15 through 24 contain the pre-registered information for that provider (thus, fields 15 through 24 are associated multivalues, one value per OpenID Connect provider).

Field 15 contains the "user friendly" name of the OpenID Connect provider to display (for example, "Google+" or "AOL").  Field 16 contains the URL of an image (if available) for that provider (for example, the "Login with Google+" button image). Field 17 can optionally contain a style name (from the included style sheet specified in field 13), or explicit CSS styling, to control the display of the OpenID Connect provider information.

OpenID Connect providers can provide a discovery "the authorization endpoint URL", which O4W can use to determine the other relevant URLs needed for OpenID Connect (for example, the discovery endpoint URL for Google is currently https://accounts.google.com/.well-known/openid-configuration).  If available, this discovery endpoint url should be specified in field 18.  If a discovery endpoint URL is not available for a specific OpenID Connect provider (or if you wish to explicitly specify the other endpoint URLs to improve performance), they should be specified in field 19 (the authorizatione endpoint URL), field 20 (the token endpoint URL), and field 21 (the dynamic registration endpoint URL, if dynamic registration is supported for this OpenID Connect provider).

After pre-registering your application with an OpenID Connect provider, you will be given a unique client ID and possibly a "client secret".  These should be put into field 22 (the client ID) and field 23 (the client secret).  During the pre-registration process, you will be required to specify one or more "redirect URLs", which tell the OpenID Connect provider what URLs are valid for your application.  These URLs should be the full URL to O4W_LOGIN - for example, http://www.mysite.com/myapp/oecgi4.exe/O4W_LOGIN and/or https://www.mysite.com/myapp/oecgi4.exe/O4W_LOGIN.  Put the desired redirect URL (which must be amongst those specified during the pre-registration process) into field 24.


Example OpenID Configuration Record

1. 1
2. OPENID
3. 1
4. 1ý1
5.
6.




Example OpenID Connect Configuration Record

1. 2
2. OPENID
3. 1
4. 1ý1
5.
6.
7.
8.
9.
10.
11. 0
12. O4W Example Application
13. ../stylesheet/oidc.css
14. 
15. Google+
16. ../images/googleplus.png
17. style="background-color:blue"
18. https://accounts.google.com/.well-known/openid-configuration
19.
20.
21.
22. 806530045098-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com
23. ZZxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxyJ
24. http://www.mysite.com/myapp/oecgi4.exe/O4W_LOGIN