OpenID Connect for MyProxy
Protocol Specification
Version 0.3 (June 2015 - IN PROGRESS)
Jim Basney <jbasney@illinois.edu>
Jeff Gaynor <gaynor@illinois.edu>
Wendy Edwards <wedwards@illinois.edu>
http://goo.gl/VnMKXS
Note: this document has evolved over time, from before the OIDC Core spec was officially released. As such, there are references to pre-Core spec documents which no longer exist, as well as parameters which have changed slightly. For this reason, it may make sense to archive this document and replace it with a new spec which references only the OIDC Core spec.
Table of Contents
OpenID Connect Required Endpoints
OpenID Connect Optional Endpoints
OA4MP Application Specific Endpoints
OpenID Connect Message Specification
Service Provider Grants Authorization
Authorization Server Authenticates End User
Mandatory Implementation Details
OAuth for MyProxy GetCert Endpoint
Get Certificate Error Response
OAuth for MyProxy Client Registration
Introduction
This document is a draft of a protocol specification for OpenID Connect (OAuth 2.0) to be used in OAuth for MyProxy. It uses the OpenID Connect Authorization Code Flow. The intended audience for this document is developers of OpenID Connect for MyProxy clients and servers.
Most of the document is a non-normative summary of the OpenID Connect protocol, with links back to the relevant normative OpenID Connect proposal specification(s). The MyProxy-specific additions are the GetCert and Client Registration endpoints.
NOTE: When this document was first written, most of the various aspects of OpenID Connect were still in development. Thus, most of the openid.net links to the OIDC spec have been superceded by the official OpenID Connect Core 1.0 Spec.
Protocol Endpoints
Three types of endpoints are used: the standard OpenID Connect required Authorization and Token endpoints, the standard OpenID Connect optional UserInfo endpoint, and the new MyProxy-specific GetCert and Client Registration endpoints.
OpenID Connect Required Endpoints
Description | Default Endpoint URL |
Authorization | https://myproxy.example.edu/oauth2/authorize |
Token | https://myproxy.example.edu/oauth2/token |
OpenID Connect Optional Endpoints
Description | Default Endpoint URL |
UserInfo | https://myproxy.example.edu/oauth2/userinfo |
OA4MP Application Specific Endpoints
Description | Default Endpoint URL |
Resource Request | https://myproxy.example.edu/oauth2/getcert |
Client Registration | https://myproxy.example.edu/oauth2/register |
Sequence Diagram
The numbers correspond to the steps in the authorization code flow (http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth , previously http://openid.net/specs/openid-connect-standard-1_0.html#code_flow).
- Client prepares an Authorization Request containing the desired request parameters.
- Client sends a request to the Authorization Server.
- Authorization Server Authenticates the End-User.
- Authorization Server Obtains the End-User Consent/Authorization.
- Authorization Server Sends the End-User back to the Client with an Authorization Code.
- Client requests a response using the Authorization Code at the Token Endpoint, per Section 3.
- Client receives a response that contains an Access Token and ID Token in the response body.
- Client validates the ID Token and retrieves the End-User's subject identifier.
- (OPTIONAL) Client accesses the UserInfo Endpoint with the Access Token, per Section 4.
- (OPTIONAL) Client receives UserInfo Response.
OpenID Connect Message Specification
Per http://openid.net/specs/openid-connect-core-1_0.html#TLSRequirements (previously http://openid.net/specs/openid-connect-standard-1_0.html#TLS_requirements), implementations must support TLS and TLS is used to communicate with the authorization endpoint. A TLS server certificate check must be performed when using TLS.
All OAuth protocol parameters MUST be transmitted via HTTP request URI query (i.e., URL encoded).
OpenID Connect specifications require that the authorization server support both GET and POST request methods, and the client may use either to send an authorization request to the server. The authorization URL must use TLS ( http://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint , previously http://openid.net/specs/openid-connect-standard-1_0.html#auth_request).
The following subsections describe the standard OpenID Connect endpoints (specified at http://openid.net/specs/) which are used by OAuth for MyProxy. They should be considered non-normative. Refer to the source OpenID Connect specifications for authoritative details.
For the new OAuth for MyProxy endpoints, skip to the OAuth for MyProxy GetCert Endpoint section below.
Client Requests Authorization
Authorization Request
Per http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest (previously http://openid.net/specs/openid-connect-standard-1_0.html#RequestParameters), these are the parameters used in OpenID Connect authorization requests. (See also http://openid.net/specs/openid-connect-messages-1_0.html#Messages for more detail).
Name | Required | Description |
response_type | REQUIRED | Must be code, token or id_token or some combination of these. |
client_id | REQUIRED | Previously registered OAuth 2.0 Client Identifier. |
scope | REQUIRED | Space delimited, case sensitive list of ASCII OAuth 2.0 scope values. The following values are supported:
For more information about scope, please see http://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims and http://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess (previously http://openid.net/specs/openid-connect-messages-1_0.html#scopes). |
redirect_uri | REQUIRED | Previously registered Redirection URI. See http://openid.net/specs/openid-connect-registration-1_0.html |
state | RECOMMENDED | Opaque value to maintain state between request and callback. Recommended for CSRF protection. See RFC 6749 Section 10.12. |
nonce | OPTIONAL | String used to associate client session with ID token. See http://openid.net/specs/openid-connect-core-1_0.html#NonceNotes . |
prompt | OPTIONAL | Space delimited, case sensitive list of ASCII string values. Defined values are: none, login, consent, and select_account |
max_age | OPTIONAL | If the elapsed time is greater than number of seconds since the user was authenticated, the OP MUST attempt to actively re-authenticate the End-User. |
id_token_hint | OPTIONAL | If the End-User identified by the ID Token is logged in or is logged in by the request, then the Authorization Server returns a positive response;otherwise, it SHOULD return an error, such as login_required. |
request | OPTIONAL | Server support of this is optional, but if not implemented, server MUST return request_not_supported error. |
request_uri | OPTIONAL | Server support of this is optional, but if not implemented, server MUST return request_uri_not_supported error |
Note: Not using the STATE parameter has led to some vulnerabilities in OAuth.
Methods
There are three OpenID Connect methods to create and send a request to the authorization endpoint: Simple Request Method, Request Parameter Method, and Request File Method. Only the Simple Request Method is supported at this time.
Example
Client redirects browser with request
HTTP/1.1 302 Found
Location: https://myproxy.example.edu/authorize?
response_type=code
&client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fmyproxy.example.edu%2Fcb
&scope=openid%20edu.uiuc.ncsa.myproxy.getcert
&nonce=n-0S6_WzA2Mj
&state=af0ifjsldkj
Browser issues GET to Authorization URL
(From http://openid.net/specs/openid-connect-standard-1_0.html#SimpleRequestMethod)
GET https://myproxy.example.edu/op/authorize?
response_type=code
&client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fmyproxy.example.edu%2Fcb
&scope=openid%20edu.uiuc.ncsa.myproxy.getcert
&nonce=n-0S6_WzA2Mj
&state=af0ifjsldkj
Service Provider Grants Authorization
Authorization Server Authenticates End User
The authorization server must validate the request according to Section 5,1 of OpenID Connect Messages 1.0. See http://openid.net/specs/openid-connect-core-1_0.html#AuthRequestValidation (previously http://openid.net/specs/openid-connect-messages-1_0.html#Validation).
In particular, the following validation steps must be performed by the authorization server endpoint:
- must validate all OAuth 2.0 parameters according to OAuth 2.0 spec
- verify "scope" contains at least "openid"
- verify all REQUIRED parameters are present and valid
- if client passed in id_token_hint, the Authorization Server MUST only send a positive response if the End-User identified by that sub (Subject) value has an active session with the Authorization Server or has been Authenticated as a result of the request.
- should ignore unrecognized request parameters
- if any errors encountered, must return an error response (in 3.1.2.6)
If the end-user is not already logged in or the authorization request contains a prompt parameter with the value "login," the authorization server must attempt to authenticate the user. If the user is not already logged in and the request contains a prompt parameter with the value "none", the authorization server must return an error.
Obtaining Consent
NOTE: The section discussing consent has been significantly reduced in the final OpenID Connect 1.0 Spec. Additionally, if "prompt" includes "consent", the Authorization Server SHOULD prompt the end-user for consent, but this is not mandatory. If the Authorization Server cannot obtain consent, it MUST return an error such as consent_required.
In OpenID Connect, the authorization server must obtain consent and authorization from the end user if the client has not been pre-authorized or the authorization request contains the prompt parameter with the value "consent". If the request has not been pre-authorized and the authorization request contains the prompt parameter with the value "none", the authorization server must return an error.
End User Agrees
If the end user agrees, the authorization server issues an authorization response. Please see http://openid.net/specs/openid-connect-standard-1_0.html#art_res_ok and http://openid.net/specs/openid-connect-messages-1_0.html#AuthzResponse .
End User Declines
If the end user declines, the authorization server must return an error response. See http://openid.net/specs/openid-connect-standard-1_0.html#authz_error .
Error Response
Name | Required | Description |
error | REQUIRED | Error code. |
error_description | OPTIONAL | Human-readable ASCII encoded text description of the error. |
error_uri | OPTIONAL | Human-readable ASCII encoded text description of the error. |
state | REQUIRED if the Authorization Request included the state parameter | OAuth 2.0 state value. Set to the value received from the Client. |
Example
From http://openid.net/specs/openid-connect-standard-1_0.html#authz_error
HTTP/1.1 302 Found
Location: https://myproxy.example.edu/cb?
error=invalid_request
&error_description=
the%20request%20is%20not%20valid%20or%20malformed
&state=af0ifjsldkj
Authorization Response
Name | Required | Description |
code | REQUIRED if the response_type in the request was code | The authorization code generated by the authorization server (per OAuth 2.0 spec). |
state | REQUIRED if the Authorization Request included the state parameter | The exact value received from client (if applicable). |
The redirection URL should be part of the authorization response. For more information, see http://tools.ietf.org/html/rfc6749#section-4.1.2 .
Note: At this point, we are only supporting "code" (i.e. Authorization Code Flow) as a response_type in the authorization request, so the authorization response would not include token or token_type. If we support "token" as a response_type in the future, then the authorization response would include token and token_type for those requests.
Example
From http://openid.net/specs/openid-connect-standard-1_0.html#art_res_ok
Response type is code
Server redirects browser to client with a URL that has a code parameter.
HTTP/1.1 302 Found
Location: https://myproxy.example.edu/cb?
code=Qcb0Orv1zh30vL1MPRsbm-diHiMwcLyZvn1arpZv-Jxf_11jnpEX3Tgfvk
&state=af0ifjsldkj
Token Endpoint
The token endpoint handles requests for retrieving and refreshing access tokens, ID tokens, and other variables. Clients must send requests to the token endpoint via HTTP POST. Clients may also provide authentication parameters in the requests. See http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint (previously http://openid.net/specs/openid-connect-messages-1_0.html#token_ep) for specifications.
Getting an Access Token
To retrieve an access token using the authorization code flow, a client must have an authorization code. See http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth (previously http://openid.net/specs/openid-connect-standard-1_0.html#code_flow) for more information about the authorization code flow.
To obtain an access token, refresh token, or ID token, the client must authenticate to the token endpoint. See http://openid.net/specs/openid-connect-core-1_0.html#TokenRequest (previously http://openid.net/specs/openid-connect-standard-1_0.html#AccessTokenRequest).
The authorization server must respond to token requests with success or error messages. See http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse (previously http://openid.net/specs/openid-connect-standard-1_0.html#AccessTokenResponse) and http://openid.net/specs/openid-connect-core-1_0.html#TokenErrorResponse (previously http://openid.net/specs/openid-connect-standard-1_0.html#AccessTokenErrorResponse).
Access Token Request
Name | Required | Description |
grant_type | REQUIRED | Value MUST be set to "authorization_code". |
code | REQUIRED | The authorization code received from the authorization server. |
redirect_uri | REQUIRED | Must be identical to value in request |
client_id | REQUIRED if not provided HTTP Basic Authorization header | The client identifier issued at registration time. |
client_secret | REQUIRED if not provided in HTTP Basic Authorization header | The client secret issued at registration time. |
See http://tools.ietf.org/html/rfc6749#section-4.1.3 . See Section 9. "Client Authentication" for valid token endpoint authentication schemes.
Token Request Validation
From Section 3.1.3.2: The Authorization Server MUST validate the Token Request as follows:
- Authenticate the Client if it was issued Client Credentials or if it uses another Client Authentication method, per Section 9.
- Ensure the Authorization Code was issued to the authenticated Client.
- Verify that the Authorization Code is valid.
- If possible, verify that the Authorization Code has not been previously used. (NOTE HOWEVER that Section 4.1.2 of the OAuth 2.0 spec states "The client MUST NOT use the authorization code more than once. If an authorization code is used more than once, the authorization server MUST deny the request and SHOULD revoke (when possible) all tokens previously issued based on that authorization code."
- Ensure that the redirect_uri parameter value is identical to the redirect_uri parameter value that was included in the initial Authorization Request. If the redirect_uri parameter value is not present when there is only one registered redirect_uri value, the Authorization Server MAY return an error (since the Client should have included the parameter) or MAY proceed without an error (since OAuth 2.0 permits the parameter to be omitted in this case).
- Verify that the Authorization Code used was issued in response to an OpenID Connect Authentication Request (so that an ID Token will be returned from the Token Endpoint).
Example
From http://openid.net/specs/openid-connect-standard-1_0.html#AccessTokenRequest
POST /token HTTP/1.1
Host: myproxy.example.edu
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
grant_type=authorization_code&code=Qcb0Orv1zh30vL1MPRsbm-diHiMwcLyZvn1arpZv-Jxf_11jnpEX3Tgfv&redirect_uri=https%3A%2F%2Fmyproxy.example.edu%2Fcb
Below is an example where the client_id and client_secret are included in the request body rather than in the authorization header:
POST /token HTTP/1.1
Host: myproxy.example.edu
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=Qcb0Orv1zh30vL1MPRsbm-diHiMwcLyZvn1arpZv-Jxf_11jnpEX3Tgfv&redirect_uri=https%3A%2F%2Fmyproxy.example.edu%2Fcb&client_id=id12345&client_secret=somesecret12345
Access Token Response
Name | Required | Description |
access_token | REQUIRED | The access token issued by the authorization server. |
token_type | REQUIRED | The type of the token issued. Currently only "Bearer" is supported. |
expires_in | RECOMMENDED | The lifetime in seconds of the refresh token. |
refresh_token | OPTIONAL | The refresh token, which can be used to obtain new access tokens using the same authorization grant |
scope | REQUIRED (unless identical to scope requested by client) | The scope of the access token. Included in cases when the client requests something (like email) that the particular server doesn’t support. |
id_token | REQUIRED | ID Token value associated with the authenticated session (as per OIDC Core 1.0 spec) |
See http://tools.ietf.org/html/rfc6749#section-5.1
Example
From http://openid.net/specs/openid-connect-standard-1_0.html#AccessTokenResponse
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
"access_token": "SlAV32hkKG",
"token_type": "Bearer",
"refresh_token": "8xLOxBtZp8",
"expires_in": 3600,
}
Token Error Response
See Section 5.2 of OAuth 2.0 Spec (RFC6749).
Token Response Validation
From Section 3.1.3.5, the Client MUST validate the Token Response as follows:
- Follow the validation rules in RFC 6749, especially those in Sections 5.1 and 10.12.
- Follow the ID Token validation rules in Section 3.1.3.7.
- Follow the Access Token validation rules in Section 3.1.3.8.
ID Token
The contents of the ID Token are described in Section 2. When using Authorization Code Flow, there is an additional OPTIONAL field (which means we can probably ignore it).
at_hash (OPTIONAL) - Access Token hash value
ID Token Validation
The Client MUST validate the ID Token in the Token Response in the manner described in Section 3.1.3.7.
Access Token Validation
When using Authorization Code Flow, if the ID Token contains at_hash, the Client MAY use it to validate the Access Token as shown in Section 3.2.2.9. But since at_hash is optional, this validation is also optional.
The specification gives the minimum claims for the ID Token. We (as do many services) return all of the requested scopes with the access token response claims. This practically means that the getUserInfo endpoint is redundant.
Refresh Token Request
The refresh token request also requires that the client be authenticated.
Name | Required | Description |
grant_type | REQUIRED | Must be set to "refresh_token" |
refresh_token | REQUIRED | The refresh token (previously) issued to client |
scope | OPTIONAL | The scope of the access request |
client_id | REQUIRED if needed for client authentication | client_id of registered client making request |
client_secret | REQUIRED if needed for client authentication | client_secret of registered client making request |
See http://tools.ietf.org/html/rfc6749#section-6 and http://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens .
Example
POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
client_id=s6BhdRkqt3
&client_secret=some_secret12345
&grant_type=refresh_token
&refresh_token=8xLOxBtZp8
&scope=openid%20profile
Note: the specification requires that the client be authenticated, and in the example above, the client_id and client_secret are passed as part of the request
Refresh Token Response
Parameters are the same as for an access token response (see above), except that the response must not include an ID Token. Note: at this point, we are not supporting ID Tokens, so it would be the same as our specification for an access token response.
Example
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
"access_token": "TlBN45jURg",
"token_type": "Bearer",
"refresh_token": "9yNOxJtZa5",
"expires_in": 3600
}
UserInfo Endpoint
The UserInfo endpoint is an OAuth 2.0 protected resource that returns claims about the authenticated end user. To obtain these claims, the client sends a request via either the GET or POST method to the UserInfo Endpoint. The UserInfo Endpoint must use TLS. See http://openid.net/specs/openid-connect-core-1_0.html#UserInfo (previously http://openid.net/specs/openid-connect-messages-1_0.html#userinfo). The UserInfo endpoint complies with the OAuth 2.0 Bearer Token Usage (RFC6750) specification. See http://tools.ietf.org/html/rfc6750 . The UserInfo request must include an access token obtained from a successful authorization request.
The UserInfo claims are returned as members of a JSON object unless a signed or encryped response was requested during client registration. See http://openid.net/specs/openid-connect-messages-1_0.html#UserInfoResponse . This is a link to standard claims, e.g., name, profile, picture: http://openid.net/specs/openid-connect-messages-1_0.html#StandardClaims .
UserInfo Request
Name | Required | Description |
access_token | REQUIRED | Access Token obtained from an OpenID Connect Authorization Request . It is recommended that the client use the Authorization header method for all requests and that they use the GET method. The Access Token obtained from an OpenID Connect Authentication Request MUST be sent as a Bearer Token. |
See http://openid.net/specs/openid-connect-core-1_0.html#UserInfoRequest (previously http://openid.net/specs/openid-connect-messages-1_0.html#UserInfoRequest).
Example
From http://openid.net/specs/openid-connect-core-1_0.html#UserInfoRequest (previously http://openid.net/specs/openid-connect-standard-1_0.html#UserInfoRequest).
GET /userinfo HTTP/1.1
Host: myproxy.example.edu
Authorization: Bearer SlAV32hkKG
From http://tools.ietf.org/html/rfc6750#section-2.3, below is an example of a request that submits the access token as a form value using the GET method:
https://myproxy.example.edu/userinfo?access_token=8xLOxBtZp8
GET /userinfo?access_token=8xLOxBtZp8 HTTP/1.1
From http://tools.ietf.org/html/rfc6750#section-2.2, below is an example of a request that submits that access token as a form value using POST
https://myproxy.example.edu/userinfo
POST /userinfo HTTP/1.1
Host: myproxy.example.edu
Content-Type: application/x-www-form-urlencoded
Content-Length: 85
access_token=8xLOxBtZp8
UserInfo Response
The UserInfo claims are returned in the form of a JSON object. More information about the claim fields can be found at http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims (previously http://openid.net/specs/openid-connect-messages-1_0.html#StandardClaims).
Example
From http://openid.net/specs/openid-connect-standard-1_0.html#UserInfoResponse
HTTP/1.1 200 OK
Content-Type: application/json
{
"sub": "jdoe",
"name": "Jane Doe"
"given_name": "Jane",
"family_name": "Doe",
"email": "janedoe@example.com",
"picture": "http://example.com/janedoe/me.jpg"
}
The Subject (sub) member contains the MyProxy username. NOTE: This is specific to the vanilla OIDC/OA4MP implementation. Other "spins" (such has one for CILogon) will use a different "sub" value.
UserInfo Error Response
From http://openid.net/specs/openid-connect-core-1_0.html#UserInfoError, example error response:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
UserInfo Response Validation
The client MUST validate the UserInfo Response as follows:
- Perform a TLS server certificate check as per http://tools.ietf.org/html/rfc6125 .
- If Client registered with userinfo_encrypted_response_alg, decrypt the UserInfo Response using the registered key.
- If the response is signed, the Client SHOULD validate the signature.
Mandatory Implementation Details
As shown at http://openid.net/specs/openid-connect-core-1_0.html#ServerMTI , the server must implement the following.
- Signing ID Tokens with RSA SHA-256 - this does NOT apply to OIDC/OA4MP since the server is using Authorization Code Flow and thus only supports returning ID Tokens from the Token Endpoint, and clients register with "none" as the requested ID Token signing algorithm.
- Prompt Parameter - as defined in http://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint , including the user interface behaviors such as "none" and "login".
- Display Parameter - the minimum level of support required is simply that the use of the parameter must not result in an error.
- Preferred Locales - the minimum level of support required is simply that the use of the parameter must not result in an error.
- Authentication Time - if requested, server must return the auth_time claim
- Maximum Authentication Age - server must support enforcing maximum authentication age via the max_age parameter
- Authentication Context Class Reference - the minimum level of support required is simply that the use of the parameter must not result in an error.
OAuth for MyProxy GetCert Endpoint
The OAuth for MyProxy GetCert endpoint is an OAuth 2.0 protected resource that returns an X.509 certificate chain (one or more certificates). To obtain the certificate, the client sends a GET or POST request including an access token obtained from a successful authorization request, plus the client_id and client_secret for protection against access token theft. The certificate chain is returned as in OAuth for MyProxy 1.0 (except without the username).
Get Certificate Request
Name | Required | Description |
client_id | REQUIRED if not provided HTTP Basic Authorization header | The client identifier issued at registration time. |
client_secret | REQUIRED if not provided in HTTP Basic Authorization header | The client secret issued at registration time. |
access_token | REQUIRED | OIDC (OAuth 2.0) access token obtained with token request. Provided in “Authorization: Bearer” header or as form value. |
certreq | REQUIRED | Base64 encoding of a DER format PKCS#10 certificate request. It MUST contain a 2048 bit RSA key. |
certlifetime | OPTIONAL | Requested certificate lifetime (in seconds) |
POST Example
POST /getcert HTTP/1.1
Host: myproxy.example.edu
Content-Type: application/x-www-form-urlencoded
client_id=s6BhdRkqt3&client_secret=some_secret12345&access_token=8xLOxBtZp8&certlifetime=950400&certreq=MIICVDCCATwCAQAwETEPMA0GA1UEAxMGaWdub3JlMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB%0ACgKCAQEAhUKrBs9%2B1GLUmfWjluNZVjud7%2Fnin0sdmOYQHB2a2pBqdSQ3hG2wG0x9%2FNsst9AGiQ%2Fh%0AQ1LoR4uOARyBd8d5cJ7UOwN%2BtktkMovLgM4GcnCkVPsUEcA7ZrbbCLWzfTgU25PuCdrlFF8xaahX%0AvR%2Bivcs%2FKKjAV4UCTNI9ft%2Bwxg%2FE5JbQGpQZrIi8o%2B79MwzgdxvJfFVg0ZBDzNEB%2F7n10TYSW0Ez%0AxmJABK6EouuaVmZCmLxoVfpwrn1%2BgfJPAPCWb27CXMCKt5zHmBKG7LbKD3hJhyZ25MzZEu4R67eT%0AAEVuy5MaydhcW8rP%2FszGwZ5r%2B%2BtCFSCmNet9bwmaZkdlsQIDAQABMA0GCSqGSIb3DQEBBQUAA4IB%0AAQBTu7r3D%2BUMHnb6JPyTdADmep%2BxBFI21wS6Z5rckvCAzAZSlcRxfGGZhrdgoOgfbE80FP1lhn1%2B%0Agvm13ku%2B4kCc1I8r7FwIOs7vCd2g%2B6gus%2BvgBM0hCxfuyNvRzbLtMbudj%2BPOReQMf0Y6%2Bng89DmW%0AXtm2J6ZmpaQx3fNmJ8KFtuZdzdIjQhMg6772fKTDNOvThhtrXnch%2FWt%2BTg4jES0vWzFLL4OgFbdl%0ADQX1HZXIoCjk%2BnVwTsPwm8E55p3qHKQ6fIMn0%2BCPBjz%2F6PiqxpquR9kOkqLNAXnbCOb5XwMTM26P%0AC5WtKkEnFKAdCIDAS0Uv34fwZ%2BO7fHy2eestubpf
GET Example
GET /getcert?certlifetime=950400&certreq=MIICVDCCATwCAQAwETEPMA0GA1UEAxMGaWdub3JlMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB%0ACgKCAQEAhUKrBs9%2B1GLUmfWjluNZVjud7%2Fnin0sdmOYQHB2a2pBqdSQ3hG2wG0x9%2FNsst9AGiQ%2Fh%0AQ1LoR4uOARyBd8d5cJ7UOwN%2BtktkMovLgM4GcnCkVPsUEcA7ZrbbCLWzfTgU25PuCdrlFF8xaahX%0AvR%2Bivcs%2FKKjAV4UCTNI9ft%2Bwxg%2FE5JbQGpQZrIi8o%2B79MwzgdxvJfFVg0ZBDzNEB%2F7n10TYSW0Ez%0AxmJABK6EouuaVmZCmLxoVfpwrn1%2BgfJPAPCWb27CXMCKt5zHmBKG7LbKD3hJhyZ25MzZEu4R67eT%0AAEVuy5MaydhcW8rP%2FszGwZ5r%2B%2BtCFSCmNet9bwmaZkdlsQIDAQABMA0GCSqGSIb3DQEBBQUAA4IB%0AAQBTu7r3D%2BUMHnb6JPyTdADmep%2BxBFI21wS6Z5rckvCAzAZSlcRxfGGZhrdgoOgfbE80FP1lhn1%2B%0Agvm13ku%2B4kCc1I8r7FwIOs7vCd2g%2B6gus%2BvgBM0hCxfuyNvRzbLtMbudj%2BPOReQMf0Y6%2Bng89DmW%0AXtm2J6ZmpaQx3fNmJ8KFtuZdzdIjQhMg6772fKTDNOvThhtrXnch%2FWt%2BTg4jES0vWzFLL4OgFbdl%0ADQX1HZXIoCjk%2BnVwTsPwm8E55p3qHKQ6fIMn0%2BCPBjz%2F6PiqxpquR9kOkqLNAXnbCOb5XwMTM26P%0AC5WtKkEnFKAdCIDAS0Uv34fwZ%2BO7fHy2eestubpf HTTP/1.1
Host: myproxy.example.edu
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Authorization: Bearer SlAV32hkKG
Get Certificate Response
A standard HTTP response. Any return code other than 200 indicates an error. The body of the response contains the PEM encoded certificate chain with Content-Type: text/plain.
Example
HTTP/1.1 200 OK
Content-Type: text/plain
-----BEGIN CERTIFICATE-----
MIIDzzCCAregAwIBAgIEFzQEITANBgkqhkiG9w0BAQUFADCBhTELMAkGA1UEBhMC
VVMxODA2BgNVBAoTL05hdGlvbmFsIENlbnRlciBmb3IgU3VwZXJjb21wdXRpbmcg
QXBwbGljYXRpb25zMRMwEQYDVQQDEwpKaW0gQmFzbmV5MRIwEAYDVQQDEwkxMjA1
MzU4NDgxEzARBgNVBAMTCjE4NzAwMzExMTAwHhcNMTMwOTA5MTYwNDIwWhcNMTMw
OTEwMDQwNzU5WjCBmTELMAkGA1UEBhMCVVMxODA2BgNVBAoTL05hdGlvbmFsIENl
bnRlciBmb3IgU3VwZXJjb21wdXRpbmcgQXBwbGljYXRpb25zMRMwEQYDVQQDEwpK
aW0gQmFzbmV5MRIwEAYDVQQDEwkxMjA1MzU4NDgxEzARBgNVBAMTCjE4NzAwMzEx
MTAxEjAQBgNVBAMTCTM4OTI4NDg5NzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBAIVCqwbPftRi1Jn1o5bjWVY7ne/54p9LHZjmEBwdmtqQanUkN4RtsBtM
ffzbLLfQBokP4UNS6EeLjgEcgXfHeXCe1DsDfrZLZDKLy4DOBnJwpFT7FBHAO2a2
2wi1s304FNuT7gna5RRfMWmoV70for3LPyiowFeFAkzSPX7fsMYPxOSW0BqUGayI
vKPu/TMM4HcbyXxVYNGQQ8zRAf+59dE2EltBM8ZiQASuhKLrmlZmQpi8aFX6cK59
foHyTwDwlm9uwlzAirecx5gShuy2yg94SYcmduTM2RLuEeu3kwBFbsuTGsnYXFvK
z/7MxsGea/vrQhUgpjXrfW8JmmZHZbECAwEAAaMxMC8wDgYDVR0PAQH/BAQDAgSw
MB0GCCsGAQUFBwEOAQH/BA4wDDAKBggrBgEFBQcVATANBgkqhkiG9w0BAQUFAAOC
AQEALcInsL20lw3eG4T48Qu1nCkdiyzJ0n7pBC1lhUO7DNBUfqi84YZX61yJjN/a
cLHS9cbBRNHkXD/irI1+4EGafeaNIhxVJ2qOpb5wdKefnBujF7Op0F+ZTt5BlZ8m
kwZ10R028ODQ8sMMKMdIRplZS4ONrpEjuElPiO8F3i5MyWU8KS+0hrYHliWJ5ZYq
MeiPfsmczIeUjoQMolrAlT1vVkwPsp8T3NVMk1qF1Q3brOO/VY41Lsl15RnNt49M
Uf2bQLUb/vjF+9W7WxJZJY16FqthPQWSdTByWSaZcEj1iiCdjev7YzmS3ng87LoE
0ZsnC8+ECNmU8WzuPS7hS8VcUA==
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIDpTCCAo2gAwIBAgIEb3ZpBjANBgkqhkiG9w0BAQUFADBwMQswCQYDVQQGEwJV
UzE4MDYGA1UEChMvTmF0aW9uYWwgQ2VudGVyIGZvciBTdXBlcmNvbXB1dGluZyBB
cHBsaWNhdGlvbnMxEzARBgNVBAMTCkppbSBCYXNuZXkxEjAQBgNVBAMTCTEyMDUz
NTg0ODAeFw0xMzA5MDkxNjAzMTdaFw0xMzA5MTAwNDA3NTlaMIGFMQswCQYDVQQG
EwJVUzE4MDYGA1UEChMvTmF0aW9uYWwgQ2VudGVyIGZvciBTdXBlcmNvbXB1dGlu
ZyBBcHBsaWNhdGlvbnMxEzARBgNVBAMTCkppbSBCYXNuZXkxEjAQBgNVBAMTCTEy
MDUzNTg0ODETMBEGA1UEAxMKMTg3MDAzMTExMDCCASIwDQYJKoZIhvcNAQEBBQAD
ggEPADCCAQoCggEBAKbbQNYjp+zIP1FEmiquSrfBvdKhpWnZpp7jUKvtLsYPM7nV
G3WeNABgKzGWdtEFc3p4kZB2jv0PsEPqeoFa0Moo3SInwmp56Kad77R1mTUH0rzb
2pTrtsHC/QZGvu/NTadl/ewuRssKyKg90WoJtYEkGWhmgITwfXKp9V9oZJlqHtuz
BvF8daOrbaUd/fej3YkM8SnN67/YcgYi5VlOrHLsnAiIQmQL1Vc+sdBzL1ZDjFYR
X399x3ZDSrMkmTySrwIAQwnhAOpPqSKwUico0mu06vRDrjbxZIXLE3fuck6SYVfe
KRxIwgYJyQNpDAbTBuDY8GS0emv9O6Y/Z69ql7kCAwEAAaMxMC8wDgYDVR0PAQH/
BAQDAgSwMB0GCCsGAQUFBwEOAQH/BA4wDDAKBggrBgEFBQcVATANBgkqhkiG9w0B
AQUFAAOCAQEAVWNdzh+t5H1fmz0kvSsFCA/pif7LGQXzoDyICF2WOT+mcI7wnKWH
B9TMquMh2fBs18EM3SAh/LTgQuSDPyWEAvk40GxwUYQTvjr9V+inAyxM/7zOWrh5
6Wa4y8L+TM+9xgyc8Tl1Bg3VDG6UEnrt1iCly2r/o7DDufY7bKKXjAhrAU2EY/As
VSoqddcg45/Z6Rk0AGqDM2dUmHyKoGiWi+IqyYFpM4Bo49BDuw6QoNr2CVbOLl/u
sYwB+tTZiPrk+V0UucPifx4i0FyZX0nM1JGY7pQ1ZLqU82Ser/pJ2gAZDGgBHF+F
dYMM1JhUFHqWO3p1+aDQjrGK8XkkspTMPA==
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIDezCCAmOgAwIBAgIEBy87KDANBgkqhkiG9w0BAQUFADBcMQswCQYDVQQGEwJV
UzE4MDYGA1UEChMvTmF0aW9uYWwgQ2VudGVyIGZvciBTdXBlcmNvbXB1dGluZyBB
cHBsaWNhdGlvbnMxEzARBgNVBAMTCkppbSBCYXNuZXkwHhcNMTMwOTA5MTYwMzEx
WhcNMTMwOTEwMDQwNzU5WjBwMQswCQYDVQQGEwJVUzE4MDYGA1UEChMvTmF0aW9u
YWwgQ2VudGVyIGZvciBTdXBlcmNvbXB1dGluZyBBcHBsaWNhdGlvbnMxEzARBgNV
BAMTCkppbSBCYXNuZXkxEjAQBgNVBAMTCTEyMDUzNTg0ODCCASIwDQYJKoZIhvcN
AQEBBQADggEPADCCAQoCggEBALJgJe5KQXd65Or32r02+C7GmaqhYqSMsHPCVtcu
R6qrU1tuWxBjDf9z40LGFq6YRqIqbFyrISQlVoAlBzQhd9QQLvdBh4zerbf1vwXG
KOpNlIa1lBH6PYGiMPoRc8NUk/vhoPSQukHrUteb3gwnfz0aKe7JuhPCLlzOXeau
t8766GUwkwHx9Dbzx+NAVYDXrMF6ZUmtVLCkXfonHZYqdp49yMHLC8J99bbcJhso
wAkFuwWS0VeeXWNmOPZBL9n9cdsH8GeogaTqVDXlRzeLT0CmzE3NpXwTSYiyTl9Z
PL0GDs8drollKSvlmswduyHvAYGGgBSpQQQXThHVVLJpuWECAwEAAaMxMC8wDgYD
VR0PAQH/BAQDAgSwMB0GCCsGAQUFBwEOAQH/BA4wDDAKBggrBgEFBQcVATANBgkq
hkiG9w0BAQUFAAOCAQEAY5dP0WBLDtNeV6avCC6o7oPCxTyIHKa73eMMPeXd5pSd
ARnD7KpWc+34pWvthWp6iCNmuF1EoGulnTAlY5Lt/9f/of4+N9hNFNG3Brt23CFr
VA1pHhKJStHMW3Eu/bp+I6jKHTE5nuFeKue9ySCM71G+lBQjmOlHpGeStLgVIuzK
F/v20yroYpd/tPLlIMaugF+vZFzZ7oJQe9CogiDbEG6GyLXU8GjRO3S3hnwoV8LM
+l45bNI6hYFhs1FYs5YEdGzzL8gqi0k8TnpbKldi3oZ8iAWREDiE9gcrBZwHcVSK
DP49DC7fLiWSbg5rBMAHeaAJOHXAK3vPbmO1HviPAQ==
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEIzCCAwugAwIBAgIDJLKlMA0GCSqGSIb3DQEBBQUAMHsxCzAJBgNVBAYTAlVT
MTgwNgYDVQQKEy9OYXRpb25hbCBDZW50ZXIgZm9yIFN1cGVyY29tcHV0aW5nIEFw
cGxpY2F0aW9uczEgMB4GA1UECxMXQ2VydGlmaWNhdGUgQXV0aG9yaXRpZXMxEDAO
BgNVBAMTB015UHJveHkwHhcNMTMwOTA5MTYwMjU5WhcNMTMwOTEwMDQwNzU5WjBc
MQswCQYDVQQGEwJVUzE4MDYGA1UEChMvTmF0aW9uYWwgQ2VudGVyIGZvciBTdXBl
cmNvbXB1dGluZyBBcHBsaWNhdGlvbnMxEzARBgNVBAMTCkppbSBCYXNuZXkwggEi
MA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCkARzrj/ZbinjdCJ3UhLzExsKB
/ezpVR0ibR0ebms4Nqw5nUlrPW65KVB/yYk4j860RG9FZVRaEzW8qehdhpHqlS/u
dlcgM3dE7raFbY5TS10xJUxR79rEuVMWLhpjqGStiksPwTSVoUxuGPWdOyG6woOA
wdnKzHYTupZnD8C9z9AE4J5jyrtGM4SiI/n9OZR4DuL9JEQkHhegbqWkjsVSg1Es
aqjIFW7kt1XmigRbaZt9P0+27NMZY0zIO+aJPf+q5mopOk6bu3835gb01rl/ab8H
bskfMzPF4ZlF1SYqWHtPXGD1PFNtNNDdxFSc/yjFZXA/IjeQRZpnkqJUSDRFAgMB
AAGjgc4wgcswDgYDVR0PAQH/BAQDAgSwMB0GA1UdDgQWBBTwBDOewbkKwLS4J4iJ
GaXe7FYaCjAfBgNVHSMEGDAWgBTX/KUCdjr2E/oroeDmUDXHI8d7UTAMBgNVHRMB
Af8EAjAAMDQGA1UdIAQtMCswDAYKKwYBBAGkPmQCBTAMBgoqhkiG90wFAgIDMA0G
CyqGSIb3TAUCAwIBMDUGA1UdHwQuMCwwKqAooCaGJGh0dHA6Ly9jYS5uY3NhLnVp
dWMuZWR1L2YyZTg5ZmUzLmNybDANBgkqhkiG9w0BAQUFAAOCAQEAa4AZfbmP568J
xHucCUWeJ7AXh5kKKcCAhqL9TWvHmQyKXfqqT7cOmcs9ln/eqNSK7/UEfJzz4+oM
2lVx7aDxa4ADZcdFzwDUXSnyb33/1OvKTinEVrc9PgIbp8thqcqmXY2TvdZiATla
pTjKK+/nGyArO1rFrvllI6mnQAO1RCALMQiOpyHp1m8As5p77TcI4Z/jcM/YJSiY
R61Ge6eiHSifroHWQRJyAOlNDTTTtfUqpwexi05atZve34wHA0ZTBlWnuVMegNnh
tlU8iqxdQke1KJ4o2ln6MZWaybqhV6EtM8YsNzrVKfYhfUA1VXyLnA7XQAM7lu7O
8ocVs/SNPw==
-----END CERTIFICATE-----
Get Certificate Error Response
We probably also need to define a response type for the various errors that can occur when requesting a certificate. This should also include when the original "scope" did not include edu.uiuc.ncsa.myproxy.getcert, probably "access_denied".
OAuth for MyProxy Client Registration
OAuth for MyProxy provides a web form at the Client Registration endpoint for registering clients. For example:
CILogon "Spin"
Notes
Implementation Issues
Incoming OIDC client parameters for initial authentication endpoint:
- scope (required) = "openid profile email edu.uiuc.ncsa.myproxy.getcert", and possibly others (see "Scope and Claims" section below)
- response_type (required) = "code"
- client_id (required) = pre-registered-assigned client id
- redirect_uri (required) = must match one of preregistered callback_uris
- state (recommended) = csrf mitigation
- response_mode (optional) - should probably ignore
- nonce (optional) - pass through unmodified
- display (optional) - can be ignored since "SHOULD"
- prompt (optional) = one or more of
- none - we always return error
- login, consent, select_account - ignore since "SHOULD"
- max_age - if (curr_time - authntime) > max_age, then forceAuthn in PHP code
The rest can be ignored
When CILogon skin CSS parameter #wayfcancelbutton is enabled (i.e., "Cancel" button is shown on Select an Identity Provider screen), and the user clicks the "Cancel" button, the OIDC server must respond with an error response (e.g., "access_denied") (see section 4.1.2.1 of the OAuth 2.0 spec and section 3.1.2.6 of OIDC spec). This is currently done strictly at the PHP level, but not sure if the back-end OIDC server needs to be involved in order to invalidate the transaction.
As noted in CIL-90, Jeff will revamp the Authorized 2.0 servlet to return the response as a 302 redirect, rather than in a JSON token. This will simplify the PHP code.
We should consider changing the default database encoding from latin1 to utf8 to accommodate European names. Then translate to 7-bit names only for the certificate subject DNs.
Scope and Claims
- "openid" - returns "sub" claim - This claim is mandatory. Currently database user_uid is returned. Is this okay? Yes, same as vanilla OA4MP OIDC.
- "profile" - can return the following:
- given_name claim - database first_name
- family_name claim - database last_name
- "email" - database email
- “edu.uiuc.ncsa.myproxy.getcert”
- cert_subject_dn: user certificate subject distinguished name (RFC2253 format)
Other scoped info which could be returned if we define "scopes" to match (like Google does for their login scopes):
Use a single scope "org.cilogon.userinfo" for the following (need to come up with proper claim names for these values):
- idp - entityID for Shibboleth, https://accounts.google.com/o/oauth2/auth for Google
- idp_display_name - e.g. "Yale University", "Google"
- user_uid - this is currently returned as "sub"
- serial_string - not sure this is helpful to end user
- create_time - when user first used CILogon with this IdP
- eptid (eduPersonTargetedID from Shibboleth)
- eppn (eduPersonPrincipalName from Shibboleth)
- oidc ("sub" from Google OpenID Connect)
Will probably also add new columns to user database table to support the following (note these are not "claims", still need to come up with actual claim names):
- affiliation (eduPersonScopedAffiliation from Shibboleth)
- displayname (displayName from Shibboleth, name from Google OpenID Connect)
