OIDC

CILogon provides a standards-compliant OpenID Connect (OAuth 2.0) interface to federated authentication for cyberinfrastructure (CI).

The CILogon project participates in the REFEDS OpenID Connect for Research and Education Working Group (OIDCre) for establishing OIDC interoperability profiles.

Client Registration

To get started, register your client at https://cilogon.org/oauth2/register and wait for notice of approval. Please register your callback URLs on that page with care. They are the only callback URLs that may be used by your client unless you later contact help@cilogon.org and request a change to your registration.

Client Configuration

CILogon's OpenID Connect (OIDC) discovery endpoint is:

name URL
Configuration https://cilogon.org/.well-known/openid-configuration

CILogon's OAuth 2.0 endpoints are:

name URL
Registration https://cilogon.org/oauth2/register
Authorization https://cilogon.org/authorize
Token https://cilogon.org/oauth2/token
User Info https://cilogon.org/oauth2/userinfo
X.509 Certificate https://cilogon.org/oauth2/getcert

CILogon currently supports the following requested scopes:

name description
openid required (the rest are optional)
email return user's email address
profile return user's first and last names
org.cilogon.userinfo return eppn and eptid identifiers
edu.uiuc.ncsa.myproxy.getcert return X.509 certificate from getcert endpoint

Please configure your client to request only the scope(s) it requires. CILogon will prompt users to approve release of their information to your client. The less information your client requests (via fewer scopes), the more likely users are to approve.

CILogon's Authorization endpoint supports the following optional parameters:

name description
selected_idp SAML EntityID of the user's selected identity provider. See https://cilogon.org/include/idplist.xml for the list of identity providers supported by CILogon.
skin The name of the custom CILogon interface skin for your application. Contact help@cilogon.org to request a custom skin.

See below for examples using curl, mod_auth_openidc, and OAuth for MyProxy.

User Identifiers and Other Claims

As illustrated in the examples below, CILogon supports standard OpenID Connect claims via the standard openid, email, and profile scopes, in addition to custom claims (eppn, eptid, etc.) via the org.cilogon.userinfo scope. To perform simple authentication, the openid scope is all you need. Quoting the OpenID Connect core specification:

The sub (subject) and iss (issuer) Claims, used together, are the only Claims that an RP can rely upon as a stable identifier for the End-User, since the sub Claim MUST be locally unique and never reassigned within the Issuer for a particular End-User, as described in Section 2. Therefore, the only guaranteed unique identifier for a given End-User is the combination of the iss Claim and the sub Claim.

All other Claims carry no such guarantees across different issuers in terms of stability over time or uniqueness across users, and Issuers are permitted to apply local restrictions and policies. For instance, an Issuer MAY re-use an email Claim Value across different End-Users at different points in time, and the claimed email address for a given End-User MAY change over time. Therefore, other Claims such as email, phone_number, and preferred_username and MUST NOT be used as unique identifiers for the End-User.

As the specification states, the sub claim is the user identifier that clients should rely on. CILogon provides eppn and eptid claims for applications that need insight into the SAML attributes provided to CILogon, but be aware that not all identity providers support eppn or eptid, whereas CILogon will always provide the sub claim.

CILogon's sub claim is customizable. If the default value doesn't meet your needs, please contact help@cilogon.org for assistance.

For More Info

Any questions? View our FAQ or contact help@cilogon.org.


Example using curl

Once you have a registered and approved client, it may be helpful to test/debug using curl on the command-line.

1. Authorization

First, set environment variables containing your registered and approved client_id, client_secret, and redirect_uri values. For example:

export CILOGON_CLIENT_ID=myproxy:oa4mp,2012:/client_id/6e8fdae3459dac6c685c6b6de37c188c
export CILOGON_CLIENT_SECRET=euWajTysidMofassawoigDiweoj1olwa
export CILOGON_REDIRECT_URI=https://localhost/callback

Be sure to substitute your own client values in the above commands! The CILOGON_CLIENT_SECRET value shown above is not an actual valid client_secret.

Next, visit the Authorization endpoint in your browser. For example:


Be sure to substitute your own client_id and redirect_uri values in the above example! You can experiment with requesting different scope values here. Only the openid scope is required. You must include the edu.uiuc.ncsa.myproxy.getcert scope if you want to retrieve a certificate. Remember that the redirect_uri value must exactly match one of the callback URLs you registered previously with CILogon.

After you successfully authenticate, CILogon will return your browser to the redirect_uri with a code parameter. For example:

https://localhost/callback?code=https%3A%2F%2Fcilogon.org%2Foauth2%2FauthzGrant%2F331685b3f0a1b02590e9c36e19d3381%2F1454019750150

Your browser will probably show a "connection refused" error for that localhost location. That's OK. We just need the code parameter from the browser's address bar.

Save the code in an environment variable. For example:

export CILOGON_CODE=https%3A%2F%2Fcilogon.org%2Foauth2%2FauthzGrant%2F331685b3f0a1b02590e9c36e19d3381%2F1454019750150

2. Get a Token

Now you're ready for the first curl command, to exchange the code for a token:

curl -d grant_type=authorization_code \
-d client_id=$CILOGON_CLIENT_ID \
-d client_secret=$CILOGON_CLIENT_SECRET \
-d code=$CILOGON_CODE \
-d redirect_uri=$CILOGON_REDIRECT_URI \
https://cilogon.org/oauth2/token \
> cilogon-token-response.txt

perl -n -e 'print $1 if (/\"access_token\":\"([^\"]+)\"/);' \
< cilogon-token-response.txt > cilogon-token.txt

export CILOGON_TOKEN=`cat cilogon-token.txt`

In the above example, we use perl to parse the response and store the token value in an environment variable. The response (stored in the cilogon-token-response.txt file) will look similar to the following:

{
"access_token":"https://cilogon.org/oauth2/accessToken/7a6ad5071df6ab080a8e6b907705907/1454449141041",
"refresh_token":"https://cilogon.org/oauth2/refreshToken/cc0c63b095269293623bc2a9b18074b/1454449141041",
"id_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJpZHBfbmFtZSI6IlVuaXZlcnNpdHiOjE0NTQ0NDkxNDEsImF1dGhfdGltZSI6IjE0NTQ0NDkxMTEifQ.",
"token_type":"Bearer",
"expires_in":900
}

We stored the access_token value in the CILOGON_TOKEN environment variable for the next step.

3. Get UserInfo

Next, you can use the token to get your user information:

curl -d access_token=$CILOGON_TOKEN \
https://cilogon.org/oauth2/userinfo

The command should produce output similar to the following:

{
"sub":"http://cilogon.org/serverA/users/534",
"idp_name":"University of Illinois at Urbana-Champaign",
"idp":"urn:mace:incommon:uiuc.edu",
"affiliation":"employee@illinois.edu;member@illinois.edu;staff@illinois.edu",

"eppn":"jbasney@illinois.edu",
"eptid":"urn:mace:incommon:uiuc.edu!https://cilogon.org/shibboleth!cyXC3O5fi0t1NBsW1NsOxZDyDd4=",
"name":"James Alan Basney",
"given_name":"James",
"family_name":"Basney",
"email":"jbasney@illinois.edu"
}

4. Get a Certificate

Lastly, you can use your token to get a certificate. First, generate a private key and certificate request:

openssl genrsa -out key.pem 2048
openssl req -new -key key.pem -subj "/CN=ignore" -out req.pem
perl -n -e 'chomp $_; print $_ if (!/----/);' < req.pem > req2.pem

Then, submit the certificate request to the GetCert endpoint to retrieve a certificate:

curl -d access_token=$CILOGON_TOKEN \
-d client_id=$CILOGON_CLIENT_ID \
-d client_secret=$CILOGON_CLIENT_SECRET \
--data-urlencode certreq=`cat req2.pem` \
https://cilogon.org/oauth2/getcert

The command should return a certificate in the output. For example:

-----BEGIN CERTIFICATE-----
MIIEwjCCA6qgAwIBAgIDCJf8MA0GCSqGSIb3DQEBCwUAMGoxEzARBgoJkiaJk/IsZAEZFgNvcmcx
FzAVBgoJkiaJk/IsZAEZFgdjaWxvZ29uMQswCQYDVQQGEwJVUzEQMA4GA1UEChMHQ0lMb2dvbjEb
MBkGA1UEAxMSQ0lMb2dvbiBCYXNpYyBDQSAxMB4XDTE2MDEyODIyNTQzNVoXDTE2MDIwNzIyNTkz
NVowgYwxEzARBgoJkiaJk/IsZAEZFgNvcmcxFzAVBgoJkiaJk/IsZAEZFgdjaWxvZ29uMQswCQYD
VQQGEwJVUzEzMDEGA1UEChMqVW5pdmVyc2l0eSBvZiBJbGxpbm9pcyBhdCBVcmJhbmEtQ2hhbXBh
aWduMRowGAYDVQQDExFKYW1lcyBCYXNuZXkgQTUzNDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBANn8yj3YNatRWDNdSrn+ZnNiBn0NdqfkiCaJQRiPXo3qRdFMggoXTyCl8RxW4VuSzV2w
U6SEFq/ofz/VoTiDG5o5RxRxo10hkelTmMoH+75ObMMY0NMgMWmid9Z57J/9lPpu8pYrjm0yVBlm
lbep38eADdYzlijTZCgBVlI2tRQeAuaaslx/y4YQrsQs+s3jl34heZ/uod3c9rmdlgK2ZAs8XI0p
Fq5qxwSujQ+/yoDXFAegPtNNoCH+xAT+O9vALeOnKCrnCyz9M2CmY8mY94LOqgXXeyFt6NRXhjsg
u4eOZPA8zUHXJLv5s6ln23tfo4COv54jxPYUxnANfh3IUS0CAwEAAaOCAUwwggFIMCUGCysGAQQB
riMBAQEGBBYMFGpiYXNuZXlAaWxsaW5vaXMuZWR1MGcGCysGAQQBriMBAQEKBFgMVnVybjptYWNl
OmluY29tbW9uOnVpdWMuZWR1IWh0dHBzOi8vY2lsb2dvbi5vcmcvc2hpYmJvbGV0aCFjeVhDM081
ZmkwdDFOQnNXMU5zT3haRHlEZDQ9MAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgSwMBMGA1Ud
JQQMMAoGCCsGAQUFBwMCMCcGA1UdIAQgMB4wDQYLKwYBBAGCkTYBAgQwDQYLKoZIhvdMBQICBgEw
OQYDVR0fBDIwMDAuoCygKoYoaHR0cDovL2NybC5jaWxvZ29uLm9yZy9jaWxvZ29uLWJhc2ljLmNy
bDAfBgNVHREEGDAWgRRqYmFzbmV5QGlsbGlub2lzLmVkdTANBgkqhkiG9w0BAQsFAAOCAQEAH9Mw
NRkJ2u+dePsJ7P+gh/swIlxVTUyCZe4yqIUAI7lCzXmWyQq4kuhqms+YFA6xF73MWB/CPTq7FRg5
cmvvTb1hMb6o3wUTZW5iVWQniMuzucfv+Qy9yfvZX7WCL5mfvRptD8U0XB1bkOus+6TEs0U46mvG
BqzIE0C6wzjtoz1+bvZOd+lXQ2tor1NbB43NhmPO+y4AiT/kk3ox1YC9cAbx4Nw+s9zug7Bb+QV/
p/MaRJxjnxcjZYOG6XK9NjyLhAOscv0CBa5PiFic6ztMqxhwNcQso+elAS9XjMdTdqEmckwL52gS
mp+XI/zv2Ys5TrpHBKHTt5H9a0Eszj3+jw==
-----END CERTIFICATE-----


Example using mod_auth_openidc

mod_auth_openidc is an Apache HTTPD 2.x module which provides client authentication to an OpenID Connect server. It can be used to restrict access to a directory using OpenID Connect authentication. HTTP header variables are populated with OIDC claims which can be used to identify the user.

1. Install mod_auth_openidc - Download the latest version for your operating system from the Releases page. Consult documentation for your O/S on specific installation instructions. Note that other software may be required by mod_auth_openidc for installation. For example, the RPM for CentOS requires libhiredis.so which is provided by the hiredis-devel RPM available from the EPEL repository.

2. Register your client - Use the instructions above to register your client. For this example, assume that the hostname is www.example.org, and we require OpenID Connect authentication to the https://www.example.org/oidc/ directory. Your HTTPD server should be configured for https connections. You can use a self-signed certificate for testing purposes. Note that the Callback URL refers to an empty directory within the /oidc/ directory. This is a requirement of mod_auth_openidc for proper redirection.

Client Name:
My Example Client
Contact Email:
help@example.org
Home URL:
https://www.example.org/
Callback URL(s):
https://www.example.org/oidc/redirect

After you click the "submit" button, the next page will show you your "client identifier" and "client secret". SAVE THESE VALUES as only you have access to the "client secret". You will need both values in the configuration section below.

3. Configure mod_auth_openidc - In the configuration directory for your Apache HTTPD installation (on CentOS, this is /etc/httpd/conf.d/), create a new file openidc.conf with the following configuration. Enter your "client identifier" and "client secret" you got from the previous step. Also set a passphase of your choosing.
LoadModule auth_openidc_module /usr/lib64/httpd/modules/mod_auth_openidc.so
OIDCProviderMetadataURL https://cilogon.org/.well-known/openid-configuration
OIDCClientID "YOUR CLIENT IDENTIFIER" OIDCClientSecret "YOUR CLIENT SECRET" OIDCRedirectURI https://www.example.org/oidc/redirect OIDCScope "openid email profile org.cilogon.userinfo" OIDCCryptoPassphrase "A PASSPHRASE OF YOUR CHOOSING" <Location /oidc/> AuthType openid-connect Require valid-user </Location>
Note that you will need to reload the httpd service configuration after creating this file. On CentOS, this can be accomplished as root with "service httpd reload".

4. Set up the "oidc" directory - In the Apache HTTPD DocumentRoot directory (on CentOS, this is /var/www/html/), create new directorires "oidc" and "oidc/redirect" and a simple file to test your setup. Below is an example PHP script which prints out the HTTP header variables set by the mod_auth_openidc module.
mkdir -p /var/www/html/oidc/redirect echo '<html><head><title>OIDC Variables</title></head><body> <table> <?php ksort($_SERVER); foreach ($_SERVER as $key => $value) { if ((preg_match('/^OIDC/',$key)) ||
(preg_match('/^REMOTE_USER/',$key))) {
echo "<tr><td>$key</td><td>$value</td></tr>\n"; } } ?> </table> </body></html>' > /var/www/html/oidc/index.php
5. Test your setup - Open a web browser, go to https://www.example.org/oidc/index.php , select an identity provider, authenticate with your chosen identity provider, and view the results. Here is example output using Google as the Identity Provider:
OIDC_CLAIM_aud myproxy:oa4mp,2012:/client_id/43e14600b717850993fdc2cae9096f6e5 OIDC_CLAIM_auth_time 1452882451 OIDC_CLAIM_email johndoe@gmail.com OIDC_CLAIM_exp 1452883351 OIDC_CLAIM_family_name Doe OIDC_CLAIM_given_name John OIDC_CLAIM_iat 1452882451 OIDC_CLAIM_idp http://google.com/accounts/o8/id OIDC_CLAIM_idp_name Google OIDC_CLAIM_iss https://cilogon.org OIDC_CLAIM_name John Doe OIDC_CLAIM_nonce h4XYvjDIjeiieZpgIaktGKGgbfcLgzCh_IASh4ige6M4 OIDC_CLAIM_oidc 103128145647504487161 OIDC_CLAIM_openid https://www.google.com/accounts/o8/id?id=AItOawngeTuRlYDj3ifDis5Cci8e0-E-rh329fg OIDC_CLAIM_sub http://cilogon.org/serverA/users/1234 OIDC_access_token https://cilogon.org/oauth2/accessToken/4871b3cb13982468b4e41f940ffd5d2c1/1451657451704 OIDC_access_token_expires 1452883351
REMOTE_USER http://cilogon.org/serverA/users/1234@cilogon.org
The OIDC_CLAIM_sub value is a CILogon-specific identifier that is unique and persistent for the user. Alternatively, REMOTE_USER can be used since (by default) mod_auth_openidc forms this value from OIDC_CLAIM_sub and OIDC_CLAIM_iss as "sub@iss"

6. Handling Errors - In the default configuration, mod_auth_openidc simply prints out the error message and description thrown by OpenID Connect Providers. You can configure mod_auth_openidc to redirect to a different page where you can better handle OIDC errors. Add the following line to your openidc.conf file:

OIDCHTMLErrorTemplate /etc/httpd/conf.d/oidcErrorTemplate.html

This HTML file can reside anywhere, but must be readable by the Apache httpd process. Then create the HTML file as follows:

echo '<html><body onload="document.forms[0].submit()">
  <form method="post" action="http://www.example.org/error">
    <input name="error" value="%s">
    <input name="error_description" value="%s">
  </form>
</body></html>' > /etc/httpd/conf.d/oidcErrorTemplate.html

Change http://www.example.org/error to a valid location on your server which can handle the submitted form. Note that you will need to reload the httpd service configuration to pick up the new error template file.

Example using OAuth for MyProxy (OA4MP)

Below is a complete sample configuration for an OA4MP OIDC client that talks to the main CILogon server. This assumes this client has been registered and approved. You will get the client id and secret from the server at registration time.

<config>
<client name="cilogon-client">
<id>myproxy:oa4mp,2012:/client_id/7a76544eb234d6c5436fcb9f710480669</id>
<serviceUri>https://cilogon.org/oauth2</serviceUri>
<authorizeUri>https://cilogon.org/authorize</authorizeUri>
<callbackUri>https://
myclient.bigstate.edu/client2/ready</callbackUri>
<secret>qhkEE47e54sXMD1E6EpyDaauvMAu02uUoXeRlLX0o915i6Cb_GArkN</secret>
<skin>dataOne</skin> <!-- optional -->
</client>
</config>

A full explanation of OA4MP configuration files and how they work is here.