REST-API

History Key

  • New content
  • Removed content

Recent Versions

Choose two versions to compare, or click the link to view it.

  1. 12. about 2 years by tzangerl
  2. 11. about 2 years by tzangerl
  3. 10. about 2 years by tzangerl
  4. 9. about 2 years by tzangerl
  5. 8. about 2 years by tzangerl
  6. 7. about 2 years by tzangerl
  7. 6. about 2 years by tzangerl
  8. 5. about 2 years by tzangerl
  9. 4. about 2 years by tzangerl
  10. 3. about 2 years by tzangerl
  11. 2. about 2 years by tzangerl
  12. 1. about 2 years by tzangerl
 

Authentication

REST authentication happens via OAuth.simplesamlphp has a quite RESTful approach to getting these tokens, so that infrastructure can be reused

Get a request token

Endpoint

GET /api/oauth.php/request

Parameters

Encoding: www-url-encoded (e.g. ?oauth_version1.0&oauth_nonce=25f408ab389...&...)

  • oauth_version (e.g. oauth_version=1.0)
  • oauth_nonce (e.g. oauth_nonce=25f408ab389...) Uniquely generated for all requests to avoid replay attacks.
  • oauth_timestamp (e.g. 1266843120)
  • oauth_consumer_key (e.g. confusa_cli). The ID of a consumer that has been specified in the consumer registry of the Confusa SP.
  • oauth_signature_method (e.g. HMAC-SHA1). The signature method. HMAC-SHA1 is recommended.
  • oauth_signature (e.g. qHjYv%2F...). The signature over all the request parameters. The consumer secret is fed into the signature method to produce the signature. The consumer secret has been defined in the SP registry along with the key.

Returns

Encoding: www-url-encoded (e.g. oauth_token=bla&oauth_token_secret=bla2)

Success:

  • oauth_token (e.g. _b5d7921efa142f2ba...) OAuth-Request-token
  • oauth_token_secret (e.g. Request token secret

Error:

  •  HTTP status code 500 (Internal server error)

 

Authorize a request token

Endpoint

GET /api/oauth.php/authorize
! Note that you have to use Confusa's authorization endpoint, because that one authorizes more data (currently the attributes + the IdP name) than the simplesamlphp authorization endpoint. The IdP information is needed in Confusa to deduce the appropriate NREN, which is needed to know which attribute mapping Confusa should take !

Parameters

  •  oauth_token (e.g. _b5d7921efa142f2ba...) OAuth-Request-token obtained in the previous step.
  •  relayURL (e.g. mycoolportal.org.cc) The URL to which the authorization endpoint should redirect the user after authorizing the request

Returns

Encoding: www-url-encoded (e.g. ?oauth_token=_b5d7...)

Success:

  • String containing a success message

Error:

  •  HTTP status code 500 (Internal server error)

 

Note: If the user is already authenticated with the default-sp and OAuth is configured to use the default-sp, this call will be successful in the browser immediately. However, there remains the inconvenience to open the same browser window in which the Confusa authentication was made. A possibility to circumvent this is to create an OAuth request token in Confusa and let the user authorize it upon starting the application and pass the resulting access token to the application.

 

Get an access token

Endpoint

GET /api/oauth.php/access

Parameters

Encoding: www-url-encoded (e.g. ?oauth_version1.0&oauth_nonce=25f408ab389...&...)

  • oauth_version (e.g. oauth_version=1.0)
  • oauth_token (e.g. _b5d7921efa142f2ba...) OAuth-Request-token authorized in the previous step.
  • oauth_nonce (e.g. oauth_nonce=25f408ab389...) Uniquely generated for all requests to avoid replay attacks.
  • oauth_timestamp (e.g. 1266843120)
  • oauth_consumer_key (e.g. confusa_cli). The ID of a consumer that has been specified in the consumer registry of the Confusa SP.
  • oauth_signature_method (e.g. HMAC-SHA1). The signature method. HMAC-SHA1 is recommended.
  • oauth_signature (e.g. qHjYv%2F...). The signature over all the request parameters. The consumer secret and the request secret are fed into the signature method to produce the signature. The consumer secret has been defined in the SP registry along with the key.

Returns

Encoding: www-url-encoded (e.g. ?oauth_token=_2345...&oauth_token_secret=_235556....)

Success:

  • oauth_token OAuth-access-token
  • oauth_token_secret OAuth-access-token secret

Error:

  • HTTP status code 500 (internal server error)

Certificate request

Request a new certificate from a PKCS#10 request

POST /api/certificates.php

Parameters

Encoding: POST XML (e.g. ?request=<signingRequest><csr>-----BEGIN...</signingRequest>)

  • request: signing request, XML with e.g the following format
   <signingRequest>
      <csr>PKCS#10 CSR</csr>
      <emails elementCount="2"><emails>
         <email>donald@duckburg.dk</email>
         <email>nospam@mailnator.com</email>
      </emails>
   </signingRequest>

The E-Mails are the e-mail addresses that are to be included as SANs in the certificate. The RelaxNG schema that the request should follow is available here.

  • oauth_token: OAuth-Access-Token of the respective user
  • oauth_consumer_key: The ID of a consumer that has been specified in the consumer registry of the Confusa SP.
  • oauth_signature_method: The signature method. HMAC-SHA1 is recommended.
  • oauth_signature: The signature over all the request parameters. The consumer secret and the access token secret are fed into the signature method to produce the signature. The consumer secret has been defined in the SP registry along with the key.
  • oauth_nonce (e.g. oauth_nonce=25f408ab389...) Uniquely generated for all requests to avoid replay attacks.
  • oauth_timestamp (e.g. 1266843120)
  • oauth_version (e.g. oauth_version=1.0)

Returns

Encoding: www-url-encoded (e.g. auth_key=2345667)

Success:

  • HTTP header: status code: 202 (accepted)
  • HTTP header: Location: <portal-url>/api/certificates/order-number (e.g. Location: https://tcs-escience-portal.terena.org/api/certificates/897485)
  • HTTP body: status: The current processing status (initially that will probably most of the times be "Accepted")

Error:

  •  Parameters missing or containing unexpected values:
    • HTTP header: status code 400 (bad request)
    • HTTP body: message: A more verbose explanation what was bad about the request
  • OAuth-token expired or other problem with the user authentication
    • HTTP header: status code 403 (Forbidden)
    • HTTP body: message: A more verbose explanation about why the authN failed
  • Attributes are missing from the user, the user does not have the correct entitlement set, the institution is not subscribed to the use of Confusa
    • HTTP header: status code 412 (Precondition failed)
    • HTTP body: message: A more verbose explanation about what must be fixed to enable certificate request.
  • An uncaught exception happens while processing:
    • HTTP header: status code 500 (Internal server error)
    • HTTP body: exception: The exception that happened in Confusa causing all that mess.

 

Certificate download

Download a single certificate

GET /api/certificates.php/<auth_key>/<format> (e.g. GET /api/certificates/8495866/pkcs7)

Examples

Return a default - PKCS#7 - encoded certificate with identifier 8495866:

GET /api/certificates.php/8495866

Return a certificate with the complete chain (cert + CA bundle) with identifier 8495866:

GET /api/certificates.php/8495866/pkcs7_cabundle

Return a certificate in cmmf encoding with identifier 8495866:

GET /api/certificates.php/8495866/cmmf

Parameters

Encoding: www-url-encoded (e.g. auth_key=2345667)

  • all OAuth parameters (see Request a new certificate from a PKCS#10 request)

Returns

Encoding: www-url-encoded (e.g. cert=<PKCS#7 blob>) and/or XML e.g. <certificate-content>PKCS#7-blob</certificate-content>

Success:

  • The certificate is done processing and can be retrieved:
    • HTTP header: status code 200 (OK)
    • HTTP header: ETag (cert-hash)
    • HTTP body: PKCS#7 certificate url-encoded or XML-encoded, TBD
  • Certificate is still being processed:
    • HTTP header: status code 202 (accepted)
    • HTTP body: status: The current processing status

Error:

  •  Parameters missing or containing unexpected values:
    • HTTP header: status code 400 (bad request)
    • HTTP body: message: A more verbose explanation what was bad about the request
  • OAuth-token expired or other problem with the user authentication
    • HTTP header: status code 403 (Forbidden)
    • HTTP body: message: A more verbose explanation about why the authN failed
  • Attributes are missing from the user, the user does not have the correct entitlement set, the institution is not subscribed to the use of Confusa
    • HTTP header: status code 412 (Precondition failed)
    • HTTP body: message: A more verbose explanation about what must be fixed to enable certificate request.
  • Certificate does not exist
    • HTTP header: status code 404 (Not Found)
  • An uncaught exception happens while processing:
    • HTTP header: status code 500 (Internal server error)
    • HTTP body: exception: The exception that happened in Confusa causing all that mess.

Certificate listing

List all certificates of a user

GET /api/certificates.php/

Parameters

Encoding: www-url-encoded

  • all OAuth parameters (see Request a new certificate from a PKCS#10 request)
  • [beginDate]: specify an optional beginDate for the certificate-list, certificates issued before that date will not be included
  • [endDate]: specify an optional endDate for the certificate-list, certificates issued after that date will not be included

Returns

Encoding: XML (+JSON?) e.g.

<certificates elementCount="10"><certificates>
   <certificate>
      <id>/api/certificates/8495866</id>
      <status>Processed</status>
      <beginDate>2009-10-20</beginDate>
      <endDate>2010-11-20</endDate>
   </certificate>
   <certificate>
      <id>...
   </certificate>
</certificates>


RelaxNG schema for the response.

Success:

  • HTTP header: status code 200 (OK)
  • HTTP header: ETag (XML-hash)
  • HTTP body: XML message containing enumeration of certificates with links to the certificates themselves and metainformation (see above)

Error:

  •  Parameters missing or containing unexpected values:
    • HTTP header: status code 400 (bad request)
    • HTTP body: message: A more verbose explanation what was bad about the request
  • OAuth-token expired or other problem with the user authentication
    • HTTP header: status code 403 (Forbidden)
    • HTTP body: message: A more verbose explanation about why the authN failed
  • Attributes are missing from the user, the user does not have the correct entitlement set, the institution is not subscribed to the use of Confusa
    • HTTP header: status code 412 (Precondition failed)
    • HTTP body: message: A more verbose explanation about what must be fixed to enable certificate request.
  • An uncaught exception happens while processing:
    • HTTP header: status code 500 (Internal server error)
    • HTTP body: exception: The exception that happened in Confusa causing all that mess.

 

Information endpoint

Get the subject DN of certificates of the AuthN user

GET /api/infopoint.php/dn/<format>

Examples

Get the DN in OpenSSL encoding (/C=SE/O=Kiruna Mining School/CN=Sven Svensson)

GET /api/infopoint.php/dn/openssl

Get the DN in RFC2253 encoding (CN=Sven Svensson, O=Kiruna Mining School, C=SE)

GET /api/infopoint.php/dn/rfc2253

Parameters

Encoding: www-url-encoded

  • all OAuth parameters (see Request a new certificate from a PKCS#10 request)

Returns

Encoding: www-url-encoded

Success:

  • HTTP header: status code 200 (OK)
  • HTTP header: ETag (DN-hash)
  • HTTP body:  url-encoded subject DN (e.g. DN=/C=SE/O=...)

Error:

  •  Parameters missing or containing unexpected values:
    • HTTP header: status code 400 (bad request)
    • HTTP body: message: A more verbose explanation what was bad about the request
  • OAuth-token expired or other problem with the user authentication
    • HTTP header: status code 403 (Forbidden)
    • HTTP body: message: A more verbose explanation about why the authN failed
  • An uncaught exception happens while processing:
    • HTTP header: status code 500 (Internal server error)
    • HTTP body: exception: The exception that happened in Confusa causing all that mess.

Get the attributes of the authN user

GET /api/infopoint.php/user

Parameters

Encoding: www-url-encoded

  • all OAuth parameters (see Request a new certificate from a PKCS#10 request)

Returns

Encoding: XML, e.g

<user>
   <uid>jdoe@example.org</uid>
   <cn>John Doe</cn>
   <orgDN>hogwarts</orgDN>
   <orgID>dc=hwww,dc=wiz</orgID>
   <emails elementCount="1"><emails>
      <email>putter@hwww.wiz</email>
   </emails>
   <nren>magiccouncil</nren>
   <country>wi</country>
   <entitlements elementCount="2"><entitlements>
      <entitlement>witchcraft</entitlement>
      <entitlement>whitemagic</entitlement>
   </entitlements>
</user>

RelaxNG schema for the response.

Success:

  • HTTP header: status code 200 (OK)
  • HTTP header: ETag (DN-hash)
  • HTTP body:  XML response like the above

Error:

Same as infopoint.php/dn