API for obtaining client certificates

The server on can be accessed directly by a user, where he is required to authenticate and then allowed to download a client certificated, packed in a profile (eap-metadata, mobileconfig, pkcs12, pem). But not all platforms have support for importing configuration files; some operating systems only have internal APIs for configuring wireless profiles (e.g. Windows and Android). For these platforms, the server allows retrieving profiles through a web API. This is a description of the API.


For discovery, use the discovery JSON file hosted at

TODO document the format of the discovery. It is rather straightforward, but explicit documentation is better

Authorization endpoint

Build a URL for the authorization endpoint; take the authorization_endpoint string from the discovery, and add the following GET parameters:

  • response_type (set to code)
  • code_challenge_method (set to S256)
  • scope (choose between eap-metadata and mobileconfig)
  • code_challenge (a code challenge, as documented in RFC7636 section 4)
  • redirect_uri (where the user should be redirected after accepting or rejecting your application, GET parameters will added to this URL by the server)
  • client_id (your client ID as known by the server)
  • state (a random string that will be set in a GET parameter to the redirect_uri, for you to verify it’s the same flow)

You have created a URL, for example:

You open a local webbrowser to this URL on the users’ device and listen on the redirect_uri for a request to return. Upon receiving a request, reclaim focus to your application and handle the request. You may receive these GET parameters:

  • code (a code that you can use on the token endpoint)
  • error (an error message that you can present to the user)
  • state (the same value as your earlier state GET parameter)

As a reply to this request, you may simply return a message to the user stating that he should return to the application. Depending on the platform, you may also return code to trigger a return to the application.

Token endpoint

The token endpoint requires a code, which you obtain via the Authorization endpoint. Use the token_endpoint string from the discovery.

You need the following POST parameters:

  • grant_type (set to authorization_code)
  • code (the code received from the authorization endpoint)
  • redirect_uri (repeat the value used in the previous request, as mandated by RFC7636)
  • client_id (repeat the value used in the previous request, as mandated by RFC7636)
  • code_verifier (a code verifier, as documented in RFC7636 section 4)

You get back a JSON dictionary, containing the following keys:

  • access_token
  • token_type (set to Bearer)
  • expires_in (validity of the access_token in seconds)

Example HTTP conversation

POST /token.php HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Content-Length: 209


HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
Pragma: no-cache

	"access_token": "v2.local.AAAAA…==",
	"token_type": "Bearer",
	"expires_in": 3600

Generator endpoint

The generator requires an access_token, as bearer. You’ve obtained this from the token endpoint. For the URL to the generator, use the generator_endpoint string from the discovery.

POST /generate.php? HTTP/1.1
Accept: application/x-eap-config
Authorization: Bearer AAAAAA…==
Content-Type: application/x-www-form-urlencoded
Content-Length: 19


HTTP/1.1 200 OK
Cache-Control: no-store
Content-Disposition: attachment; filename="johndoe.xml"
Content-Type: application/eap-config
Pragma: no-cache

<?xml version="1.0" encoding="utf-8"?>
Last updated on 7 Sep 2020