Difference between revisions of "OAuth for MyProxy GetProxy Endpoint"

From PDP/Grid Wiki
Jump to navigationJump to search
(removed AuthZ Basic header part / reformulated GetProxy & MyProxy ca mode warning)
(fix wrong char encoding around Authorization: Bearer)
 
(24 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
[http://grid.ncsa.illinois.edu/myproxy/oauth/ OAuth for MyProxy] (OA4MP) is based around the [https://docs.google.com/document/d/1cs3peO9FxA81KN-1RC6Z-auEFIwRbJpZ-SFuKbQzS50/pub OIDC/OA4MP Protocol], which is a modified version of [http://openid.net/specs/openid-connect-core-1_0.html OpenID Connect]. The modifications introduced by OA4MP include the [https://docs.google.com/document/d/1cs3peO9FxA81KN-1RC6Z-auEFIwRbJpZ-SFuKbQzS50/pub#h.3khs91kr9igo GetCert Endpoint] which is used by the OA4MP Client (ex. Science Gateway) to retrieve an End Entity Certificate (EEC) on behalf of the authenticated user. In certain scenarios the use of EECs can be replaced by Proxy Certificates. Proxy Certificates, usually having a shorter lifetime than EECs, are less likely to be used maliciously given their short validity period, while still conveying the same authentication information as an EEC would. Moreover, a Proxy Certificate can contain additional authorization information in the form of VOMS Extensions.   
+
[http://grid.ncsa.illinois.edu/myproxy/oauth/ OAuth for MyProxy] (OA4MP) implements the [http://goo.gl/VnMKXS OIDC/OA4MP Protocol], which is an extension of the [http://openid.net/specs/openid-connect-core-1_0.html OpenID Connect] specification. The modifications introduced by OA4MP on top of OIDC include the [http://goo.gl/VnMKXS#h.3khs91kr9igo GetCert Endpoint] which is used by the OA4MP Client (e.g. a Science Gateway) to retrieve an End Entity Certificate (EEC) on behalf of the authenticated user. Typical workflows on the other hand usually do not directly make use of EECs, but instead use [https://tools.ietf.org/html/rfc3820 RFC3820] Proxy Certificates.<br>
 +
Proxy Certificates, usually having a shorter lifetime than EECs, are less likely to be used maliciously given their short validity period, while still conveying the same authentication information as an EEC would. Moreover, a Proxy Certificate can contain additional authorization information in the form of VOMS Extensions.   
  
−
We propose adding a GetProxy Endpoint into the OIDC/OA4MP Protocol, which returns Proxy Certificates. The main differences between the GetProxy and GetCert Endpoint are:
+
The AARC-developed MasterPortal therefore adds a GetProxy Endpoint to the OIDC/OA4MP Protocol, which directly returns Proxy certificate chains to its clients. The main differences between the GetProxy and GetCert Endpoint are:
  
−
* returns Proxy Certificates
+
* return RFC3820 Proxy Certificate chain
−
* generates CSR on server side instead of client side
+
* generates keypair and CSR on server side instead of client side
 
* accepts VONAME and VOMSES parameters  
 
* accepts VONAME and VOMSES parameters  
 +
 +
For the ''technical implementation details'' of the Getproxy Endpoint, see [[OAuth_for_MyProxy_GetProxy_Endpoint_-_Implementation | here]].
  
 
== Protocol Specification ==
 
== Protocol Specification ==
  
−
The GetProxy Endpoint, just like the GetCert Endpoint is an OAuth2.0 protected resource that returns a proxy certificate. This proxy certificate consists of a certificate chain and private key of the proxy. The request made to the GetProxy Endpoint is made up of the following parameters:
+
The GetProxy Endpoint, just like the GetCert Endpoint, is an OAuth2.0 protected resource that returns a proxy certificate. This proxy certificate consists of a certificate chain and private key of the proxy. The request made to the GetProxy Endpoint is made up of the following parameters:
  
 
{| class="wikitable" style="width: 55%;"
 
{| class="wikitable" style="width: 55%;"
Line 30: Line 33:
 
| style="width: 25%;" |access_token
 
| style="width: 25%;" |access_token
 
| style="width: 33%;" |REQUIRED
 
| style="width: 33%;" |REQUIRED
−
| OIDC (OAuth 2.0) access token obtained with token request. Provided in �Authorization: Bearer� header or as form value.
+
| OIDC (OAuth 2.0) access token obtained with token request. Provided in 'Authorization: Bearer' header or as form value.
  
 
|-
 
|-
Line 40: Line 43:
 
| style="width: 25%;" |voname
 
| style="width: 25%;" |voname
 
| style="width: 33%;" |OPTIONAL
 
| style="width: 33%;" |OPTIONAL
−
| Specifies one or more VO to connect to for membership information. The VO name can be followed by additional group and role request. (see 'man voms-proxy-init' under -voms)
+
| Specifies one or more VOs to connect to for membership information. The VO name can be followed by additional groups and roles. (Same format as for the ''-voms'' option to ''voms-proxy-init'', see ''man voms-proxy-init'').
  
 
|-
 
|-
 
| style="width: 25%;" |vomses
 
| style="width: 25%;" |vomses
 
| style="width: 33%;" |OPTIONAL
 
| style="width: 33%;" |OPTIONAL
−
| Specifies VOMS server information under 'vomses' file format
+
| Specifies VOMS server information in 'vomses' file format.
  
 
|}
 
|}
  
−
Just like in case of GetCert, the access_token, client_id and client_secret parameters are there to ensure the authenticity of the request. Note that the 'certreq' parameter, containing the Certificate Signing Request (CSR), is no longer sent along in the request. Instead, a new keypair and CSR are created on the server side and used in the subsequent MyProxy GET request. The motivation behind this change is to take the burden of key generation off the OA4MP Client, thus making it more lighweight and easily adaptable by different communities.
+
Just as for the GetCert endpoint, the access_token, client_id and client_secret parameters are there to ensure the authenticity of the request. Note that the 'certreq' parameter (of the getcert request), containing the Certificate Signing Request (CSR), is not required. Instead, a new keypair and CSR are created on the server side and used in the subsequent MyProxy GET request. The motivation behind this change is to take the burden of key generation away from the OA4MP Client, thus making it more lightweight and easier to adopt by different communities.
  
−
Requesting a VOMS Proxy Certificate can be done by using the 'voname' and 'vomses' request parameters. These parameters are passed as they are to the subsequent [http://grid.ncsa.illinois.edu/myproxy/protocol/ MyProxy GET] request.
+
Requesting a VOMS Proxy Certificate can be done by using the 'voname' and 'vomses' request parameters. These parameters are passed as-is to the [http://grid.ncsa.illinois.edu/myproxy/protocol/ MyProxy GET] request executed by the MasterPortal.
  
−
'''Note:''' The VOMSES string is useful in scenarios where the user would like to get membership information from a VOMS server which is not configured in the backend MyProxy Server 'vomses' file.
+
'''Note:''' The VOMSES string is useful in scenarios where the client would like to make use of a VOMS server which is not configured locally in the back-end MyProxy Server (in its 'vomses' file, see 'man myproxy-server.config' under 'voms_userconf').
  
 
=== Example Request ===
 
=== Example Request ===
Line 59: Line 62:
 
POST Example
 
POST Example
  
−
  POST /getcert HTTP/1.1
+
  POST /getproxy HTTP/1.1
−
  Host: myproxy.example.edu
+
  Host: masterportal.example.edu
 
  Content-Type: application/x-www-form-urlencoded
 
  Content-Type: application/x-www-form-urlencoded
 
   
 
   
Line 66: Line 69:
 
  voname=superscience&vomses=%22testvo%22%20%22voms.example.edu%22%20%2215000%22%20%22%2FC%3DXX%2FO%3DExample%2FCN%3Dmyproxy.example.edu%22%20%22testvo%22
 
  voname=superscience&vomses=%22testvo%22%20%22voms.example.edu%22%20%2215000%22%20%22%2FC%3DXX%2FO%3DExample%2FCN%3Dmyproxy.example.edu%22%20%22testvo%22
  
−
  curl --capath /etc/grid-security/certificates/ -H "Host: myproxy.example.edu" -H "Content-Type: application/x-www-form-urlencoded" -X POST -d \
+
  curl --capath /etc/grid-security/certificates/ -d \
 
       'client_id=s6BhdRkqt3&client_secret=some_secret12345&access_token=8xLOxBtZp8&proxylifetime=43200&
 
       'client_id=s6BhdRkqt3&client_secret=some_secret12345&access_token=8xLOxBtZp8&proxylifetime=43200&
−
       voname=superscience&vomses="testvo" "voms.example.edu" "15000" "/C=XX/O=Example/CN=myproxy.example.edu" "testvo"' \  
+
       voname=superscience&vomses="testvo" "voms.example.edu" "15000" "/C=XX/O=Example/CN=myproxy.example.edu" "testvo"' \
−
      https://myproxy.example.edu/oauth2/getproxy
+
      https://masterportal.example.edu/oauth2/getproxy
  
 
=== Example Response ===
 
=== Example Response ===
Line 115: Line 118:
 
  -----END CERTIFICATE-----
 
  -----END CERTIFICATE-----
  
−
== Implementation Details ==
+
=== Example client code ===
−
 
 
−
The implementation of the GetProxy Endpoint has been separated from the Master Portal OA4MP extension because it was found to be much easier to modify existing OA4MP code than to extend it. This basically means that for the purpose of implementing this endpoint we forked OA4MP. This custom OA4MP having the GetProxy Endpoint implemented can be found under the [https://github.com/ttomttom/myproxy-fork myproxy-fork] and [https://github.com/ttomttom/ncsa-security-all-fork/ ncsas-security-all-fork] projects. The separation of the two codebases is inherited from the original OA4MP implementation.
 
−
 
 
−
=== myproxy ===
 
−
 
 
−
==== Client ====
 
−
 
 
−
The OA4MP Client has to be able to distinguish between cases of requesting an EEC through GetCert and requesting a proxy through GetProxy, since the backend [[#Server|Server]] is configured to provide one '''OR''' the other (EEC or Proxy), '''not both'''. This is done with the use of a new [http://grid.ncsa.illinois.edu/myproxy/oauth/client/manuals/parameters.xhtml#tags OA4MP Client configuration] parameter called 'requestProxies'.
 
−
 
 
−
{| class="wikitable" style="width: 55%;"
 
−
|-
 
−
|
 
−
| Required?
 
−
| Default
 
−
| Description
 
−
 
 
−
|-
 
−
| requestProxies
 
−
| N
 
−
| false
 
−
| Enables making requests to the GetProxy Endpoint
 
−
 
 
−
|}
 
−
 
 
−
Configuration example:
 
−
 
 
−
<client name="client-config" address="https://portal.example.edu/portal">
 
−
    ...
 
−
          <requestProxies>true</requestProxies>
 
−
    ...
 
−
</client>
 
−
 
 
−
By setting this configuration to '''true''' a GetProxy Endpoint aware ''OA2MPProxyService'' object will be returned to client servlets instead of a ''OA2MPService'' object. The servlet can then request a proxy by calling the ''getProxy(OA2Asset a, ATResponse2 atResponse2)'' method of the returned object. The [[#Example Request|GetProxy request]] is build internally using the clients' ID, secret and the current transactions' access token. User input (voname and vomses) should be provided to this method via the ''OA2Asset'' parameter. The proxylifetime parameter is taken from the 'lifetime' client configuration.
 
−
 
 
−
==== Server ====
 
−
 
 
−
The OA4MP Server has both GetCert and GetProxy Endpoints available at the same time, but the MyProxy Server in its backend can only be configured to return '''either''' EEC '''or''' Proxy Certificate.
 
−
 
 
−
'''Note:''' Do NOT use the GetProxy Endpoint when the backend MyProxy Server is configured in [http://grid.ncsa.illinois.edu/myproxy/ca/ CA mode] issuing End Entity Certificates! You will end up receiving EEC from the GetProxy Endpoint.
 
−
 
 
−
The implementation of the GetProxy servlet is done in ''OA2ProxyServlet''. A successful GetProxy request will execute the following flow in the servlet:
 
−
 
 
−
[[File:Getproxy_servlet_seq.svg]]
 
−
 
 
−
* Step 1 : As mentioned above, the key and CSR generation has been moved away from the OA4MP Client into the Server. The ''verifyAndGet'' method creates a new keypair and saves the resulting private key and CSR into the transaction. The proxylifetime, voname and vomses are stripped off from the request and saved in the transaction.
 
−
 
 
−
* Step 2 : The ''checkMPConnection'' method initiates a new MyProxy connection
 
−
 
 
−
* Step 3 : The ''getX509Certificates'' method inserts the proxylifetime, voname and vomses values into the MyProxy connection after which proceeds to execute a MyProxy GET command, returning the certificate chain created.
 
−
 
 
−
* Step 4 : The ''preprocess'' method is called before the resulting certificate chain is written out into the response buffer. Here, the ''MyX509Certificates'' holding only the certificate chain is swapped out to a ''MyX509Proxy'' object containing the same certificate chain, together with the private key from the transaction (saved in Step 1).
 
−
 
 
−
=== ncsa.security.all ===
 
−
 
 
−
The '''myproxy''' project builds on top of the '''ncsa.security.all''' project, and therefore some of the modified code logically belongs into this project.
 
−
 
 
−
[[File:Ncsa-uml.svg | 1000px]]
 
−
 
 
−
The original OA4MP uses ''MyX509Certificates'' as a container to transmit and receive certificate chains. With the extension of GetProxy Endpoint, this container class is no longer sufficient to transmit proxies around, because it cannot hold the proxy's private key. A new container under the name of ''MyX509Proxy'' has been implemented which extends ''MyX509Certificates''.
 
−
 
 
−
The ''ProxyUtil'' class holds a set of static methods used for proxy transformation and generation. This class works with the aid of a newly introduced dependency: [https://github.com/eu-emi/canl-java/ canl-java]. At the time of this writing the canl version integrated was version [http://search.maven.org/#artifactdetails|eu.eu-emi.security|canl|2.2.0|jar 2.2.0].
 
  
−
A new request server called ''PPServer2'' (Protected Proxy Server 2) has been added after the model of ''PAServer2'' used for GetCert Requests. The new ''PPServer2'' class sets [[#Protocol Specification | GetProxy request parameters]] and creates a ''MyX509Proxy'' out of the response.
+
For example code, see this [https://rcdemo.nikhef.nl/demobasic/ simple PHP demonstrator], which shows how the <tt>/getproxy</tt> endpoint can be used to obtain a valid proxy certificate.

Latest revision as of 19:40, 20 October 2022

OAuth for MyProxy (OA4MP) implements the OIDC/OA4MP Protocol, which is an extension of the OpenID Connect specification. The modifications introduced by OA4MP on top of OIDC include the GetCert Endpoint which is used by the OA4MP Client (e.g. a Science Gateway) to retrieve an End Entity Certificate (EEC) on behalf of the authenticated user. Typical workflows on the other hand usually do not directly make use of EECs, but instead use RFC3820 Proxy Certificates.
Proxy Certificates, usually having a shorter lifetime than EECs, are less likely to be used maliciously given their short validity period, while still conveying the same authentication information as an EEC would. Moreover, a Proxy Certificate can contain additional authorization information in the form of VOMS Extensions.

The AARC-developed MasterPortal therefore adds a GetProxy Endpoint to the OIDC/OA4MP Protocol, which directly returns Proxy certificate chains to its clients. The main differences between the GetProxy and GetCert Endpoint are:

  • return RFC3820 Proxy Certificate chain
  • generates keypair and CSR on server side instead of client side
  • accepts VONAME and VOMSES parameters

For the technical implementation details of the Getproxy Endpoint, see here.

Protocol Specification

The GetProxy Endpoint, just like the GetCert Endpoint, is an OAuth2.0 protected resource that returns a proxy certificate. This proxy certificate consists of a certificate chain and private key of the proxy. The request made to the GetProxy Endpoint is made up of the following parameters:

Name Required Description
client_id REQUIRED The client identifier issued at registration time.
client_secret REQUIRED 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.
proxylifetime OPTIONAL Requested proxy lifetime (in seconds). In case this value exceeds the server side default, the request parameter is ignored.
voname OPTIONAL Specifies one or more VOs to connect to for membership information. The VO name can be followed by additional groups and roles. (Same format as for the -voms option to voms-proxy-init, see man voms-proxy-init).
vomses OPTIONAL Specifies VOMS server information in 'vomses' file format.

Just as for the GetCert endpoint, the access_token, client_id and client_secret parameters are there to ensure the authenticity of the request. Note that the 'certreq' parameter (of the getcert request), containing the Certificate Signing Request (CSR), is not required. Instead, a new keypair and CSR are created on the server side and used in the subsequent MyProxy GET request. The motivation behind this change is to take the burden of key generation away from the OA4MP Client, thus making it more lightweight and easier to adopt by different communities.

Requesting a VOMS Proxy Certificate can be done by using the 'voname' and 'vomses' request parameters. These parameters are passed as-is to the MyProxy GET request executed by the MasterPortal.

Note: The VOMSES string is useful in scenarios where the client would like to make use of a VOMS server which is not configured locally in the back-end MyProxy Server (in its 'vomses' file, see 'man myproxy-server.config' under 'voms_userconf').

Example Request

POST Example 

POST /getproxy HTTP/1.1
Host: masterportal.example.edu
Content-Type: application/x-www-form-urlencoded

client_id=s6BhdRkqt3&client_secret=some_secret12345&access_token=8xLOxBtZp8&proxylifetime=43200&
voname=superscience&vomses=%22testvo%22%20%22voms.example.edu%22%20%2215000%22%20%22%2FC%3DXX%2FO%3DExample%2FCN%3Dmyproxy.example.edu%22%20%22testvo%22

curl --capath /etc/grid-security/certificates/ -d \
     'client_id=s6BhdRkqt3&client_secret=some_secret12345&access_token=8xLOxBtZp8&proxylifetime=43200&
      voname=superscience&vomses="testvo" "voms.example.edu" "15000" "/C=XX/O=Example/CN=myproxy.example.edu" "testvo"' \
     https://masterportal.example.edu/oauth2/getproxy

Example Response

In case of a successful request the body of the response message contains the Proxy Certificate in PEM format. The first certificate in the chain is the proxy followed by its private key, and the rest of the chain. 

HTTP/1.1 200 OK
Content-Type: text/plain

-----BEGIN CERTIFICATE-----
MIIJ+DCCCOCgAwIBAgIEWVmVpjANBgkqhkiG9w0BAQsFADBVMQ0wCwYDVQQKEwRHcmlkMRMwEQYD
VQQLEwpHbG9idXNUZXN0MRwwGgYDVQQDFhNkdW1teUBteS1kb21haW4uY29tMREwDwYDVQQDEwg3

...

BvjdU/+9xSlBnFm7v2thFcqienTP6cY/iCQPDzT9wv/fdv/DToy9oN0BrtYievZjZOLcjsczMD5M
KXOr/StOe+qDtT6CXwpzGNE4QJYTl8yoQguZaSsGxgP2PDPS0G0dLGTv8YvG3Fle
-----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCAIZ9nkUddKLznkHuda9yRxPP5
j2JO9U0CFmr4EmKjvza8BstyndksT235zODXIs3wVVYqxxMqH4J9181MlCxs8f7GXRlgDlY3oSa/

...

eM7xUIqehh+Yy01oKEcSNE3ykvySXxp7JBvREhNCaObxpMhi0JAMaAJ0atf9e8E/DFOccy6P9McZ
ysKQufEOgePsck/OrFEDmGqs+bA=
-----END PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIIDQjCCAiygAwIBAgIEBE72YDALBgkqhkiG9w0BAQswQjENMAsGA1UEChMER3JpZDETMBEGA1UE
CxMKR2xvYnVzVGVzdDEcMBoGA1UEAxYTZHVtbXlAbXktZG9tYWluLmNvbTAeFw0xNjAxMDYxNTAx

...

XZxr1zbbcPnol8vETpTiRvW3I8ms3PBwgWXE4xIbN8Myng7UgPjasv+JOykx+3UIVD1FblZAXdnH
fBJa7cu/xGomko+7i0opoQewaRcPLmGbL6xVuW3MERwIPfiKqsz+4w==
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIICnjCCAgegAwIBAgICAMEwDQYJKoZIhvcNAQELBQAwTzENMAsGA1UEChMER3JpZDETMBEGA1UE
CxMKR2xvYnVzVGVzdDEpMCcGA1UEAxMgR2xvYnVzIFNpbXBsZSBDQSBmb3IgRGVtbyBQb3J0YWww

...

IACngeT/1vXoC/2s03B9dwK4s/pBs7EVG/9kf5Wlew3IVwtcqTI2kDXUPiLey+ro37Qct5htseft
E2TwLFzbCOo9wI/6cCu7uSOyxGwVlk+rvTfJFsaAmYOMeQuytQCTRy9loFNz6Hk=
-----END CERTIFICATE-----

Example client code

For example code, see this simple PHP demonstrator, which shows how the /getproxy endpoint can be used to obtain a valid proxy certificate.

Retrieved from "https://wiki.nikhef.nl/grid/index.php?title=OAuth_for_MyProxy_GetProxy_Endpoint&oldid=10932"