Configuring OpenConext API clients
Registering a client for the OpenConext API means that you configure specific parameters in JANUS for that client so that it can access the API. What needs to be configured depends on the security method used by the client.
When it is also a SAML SP, the OpenConext API client configuration can be added to the SP's JANUS entry. Otherwise, a new JANUS SP entry can be made with containing only the API client configuration.
##OAuth 2.0 client Follow these steps to create an OpenConext API client using OAuth 2.0 for security:
Go to https://serviceregistry.demo.openconext.org and open the JANUS module under the Federation tab.
Create or modify an SP entry, make sure to set the following parameters:
| Parameter | Description | Required / Optional | Remarks |
|---|---|---|---|
| coin:gadgetbaseurl | This is a regular expression that is used to match the OAuth 2.0 client_id | R | OAuth2.0 clients exchanging the authorization code for an access token will place the client credentials key:secret base64encoded in the Authorization header of the request, therefore the coin:gadgetbaseurl may not contain the ':' character and therefore can not be a valid UrI |
| coin:oauth:secret | This is the client secret | O | mandatory when using Authorization Code grant and optional for Implicit grant. |
| coin:oauth:callback_url | Contains the redirect_uri of the OAuth client | O | When more then one redirect URL is needed, multiple can be configured as a comma separated list. If empty the runtime redirect URL is used. For implicit grant to work the vallback uri is required. |
| coin:oauth:consent_not_required | if the consent screen of OpenConext API can be skipped | O | After the first login at this OAuth client, the user needs to give consent to release his personal information to the OAuth client. This consent screen can be eliminated for this client when this parameter is set. |
| coin:oauth:app_description | OAuth client application description | O | Displayed to a user in the consent screen. |
| coin:oauth:app_icon | The URL of the OAuth application icon image | O | Displayed to a user in the consent screen. This URL must be accessible from the internet. |
| coin:oauth:app_thumbnail | The URL of the OAuth application logo image | O | Displayed to a user in the consent screen. This URL must be accessible from the internet. |
| coin:oauth:app_title | OAuth application title | O | Displayed to a user in the consent screen |
| coin:eula | The URL of the application's EULA | O | Displayed to a user in the consent screen as a link to the application's End User License Agreement (EULA) |
More information on these parameters can be found on the Description of metadata fields page.
Although the OAuth 2.0 spec mandates that the "Authorization: Basic" header be used (with fallback to client_id and client_secret in the POST body), only this fallback is supported by OpenConext API at the moment. This is because all client_ids contain colons (as they are URIs) and colons are not allowed in usernames (RFC 2617).
Go to https://serviceregistry.demo.openconext.org and open the JANUS module under the Federation tab.
Create or modify an SP entry, make sure to set the following parameters:
| Parameter | Description | Required/ Optional | Remarks |
|---|---|---|---|
| coin:gadgetbaseurl | This is the consumer key | R | Format is a regular expression that is used to find the correct OAuth 1.0a configuration |
| coin:oauth:secret | This is the consumer secret | R | |
| coin:oauth:callback_url | Contains the redirect_uri of the OAuth client | O | When you want to enforce that the actual (runtime) callback url of the SP is checked against a pre-configured value then add this parameter |
| coin:oauth:two_legged_allowed | if the consent screen of OpenConext API can be skipped | O | To be able to make two-legged OAuth 1.0a calls to OpenConext API, this parameter needs to be set. Note that anyone using two-legged OAuth 1.0a has access to all user and group data in OpenConext. |
Go to https://serviceregistry.demo.openconext.org and open the JANUS module under the Federation tab.
Create or modify an SP entry, make sure to set the following parameters:
| Parameter | Description | Required/ Optional | Remarks |
|---|---|---|---|
| coin:gadgetbaseurl | This is the consumer key | R | Format is a regular expression that is used to find the correct OAuth 1.0a configuration |
| coin:oauth:public_key | This is the public key of the consumer application | R | Contains the public x509 certificate of the consumer application |
| coin:oauth:key_type | The key type used | R | RSA_PRIVATE |
| coin:oauth:consent_not_required | if the consent screen of OpenConext API can be skipped | O | After the first login at this OAuth client, the user needs to give consent to release his personal information to the OAuth client. This consent screen can be eliminated for this client when this parameter is set. |
| coin:oauth:app_description | OAuth client application description | O | Displayed to a user in the consent screen. |
| coin:oauth:app_icon | The URL of the OAuth application icon image | O | Displayed to a user in the consent screen. This URL must be accessible from the internet. |
| coin:oauth:app_thumbnail | The URL of the OAuth application logo image | O | Displayed to a user in the consent screen. This URL must be accessible from the internet. |
| coin:oauth:app_title | OAuth application title | O | Displayed to a user in the consent screen |
| coin:eula | The URL of the application's EULA | O | Displayed to a user in the consent screen as a link to the application's End User License Agreement (EULA) |
In the screenshot below we have the example where iGoogle is the OAuth consumer. The example below uses a public key. The extra information such as app_title, app_description, etc are showed to a user when he has to provide consent for the data request, so they give the user information about the application that wants to access his data.
Go to https://serviceregistry.demo.openconext.org and open the JANUS module under the Federation tab.
Create or modify an SP entry, make sure to set the following parameters:
| Parameter | Description | Required/ Optional | Remarks |
|---|---|---|---|
| coin:gadgetbaseurl | R | The coin:gadgetbaseurl is derived from the coin:oauth:consumer_key (so the consumer_key has to be some form of a URL). | |
| coin:oauth:consumer_key | The consumer key | R | |
| coin:oauth:secret | The consumer secret | R | |
| coin:oauth:key_type | The key type used | O | HMAC_SHA1 |
| coin:oauth:callback_url | Contains the redirect_uri of the OAuth client | O | When you want to enforce that the actual (runtime) callback url of the SP is checked against a pre-configured value then add this parameter. |
| coin:oauth:consent_not_required | if the consent screen of OpenConext API can be skipped | O | After the first login at this OAuth client, the user needs to give consent to release his personal information to the OAuth client. This consent screen can be eliminated for this client when this parameter is set. |
| coin:oauth:app_description | OAuth client application description | O | Displayed to a user in the consent screen. |
| coin:oauth:app_icon | The URL of the OAuth application icon image | O | Displayed to a user in the consent screen. This URL must be accessible from the internet. |
| coin:oauth:app_thumbnail | The URL of the OAuth application logo image | O | Displayed to a user in the consent screen. This URL must be accessible from the internet. |
| coin:oauth:app_title | OAuth application title | O | Displayed to a user in the consent screen |
| coin:eula | The URL of the application's EULA | O | Displayed to a user in the consent screen as a link to the application's End User License Agreement (EULA) |
By default, a newly registered OpenConext API client will not be allowed to retrieve groups and members of his groups. Not from the user's OpenConext Teams and not from any configured External Group Providers (EGPs).
To specifically allow access via the OpenConext API to a group provider's groups, do the following:
- Go to https://manage.demo.openconext.org
- Click on Engine Block -> Group Providers -> group provider name -> ACL.
- Check the boxes "Allow groups" and/or "Allow members" depending on the client application's requirements.
To allow access to the OpenConext Teams, use "SURFteams grouper" as the group provider name in the above procedure. If you have an EGP configured and you want this OpenConext API client to have access to it, follow the procedure again with the EGPs name.
The OpenConext API complies to the ARP set for the SP in ServiceRegistry. However, you configure the ARP in ServiceRegistry based on the SAML attribute names. These are different from the attribute names that OpenConext API returns so some type of mapping is needed.
The following strategy is used:
- No ARP: all information is returned
- Empty ARP: no information at all is returned
- ARP contains any name attributes: Display name, name and nick name are returned
- ARP contains any organization attributes: all organization information is returned
- ARP contains email attribute: all email information is returned
- ARP contains uid attribute: All account information is returned and all tags are returned
##ACL for OpenConext API clients After you register a new OpenConext API client application in ServiceRegistry, you need to review the access control list for this new application. You need to specify which IdP's can make use of this new application. There are several options:
- The registration of the new OpenConext API client is part of an existing SAML SP entry in ServiceRegistry. In this case, the ACL for the SAML part is automatically valid for the OpenConext API part.
- When you created a new SP entry for the OpenConext API client, you need to specify an ACL to allow IdPs access to it. _Note _that by default, all configured IdP's will have access to a new SP entry.
For an IdP to make use of any OpenConext API client, it first needs to be allowed access to the OpenConext API itself. So when you create or modify ACLs, make sure the IdP has access to the OpenConext API.
More specific information on ACLs for OpenConext API client applications, see the Scoping of SAML AuthnRequests page.
The OAuth1/2 flows use a client side redirect URI. This URI can be pre-registered but it also can be provided during the OAuth conversation.
The OAuth 2 specification is not clear about which one has precedence or which one is required at all times. Common sense and pre-existing implementation lead to the following rules:
- If a URL is preregistered, a redirect_uri parameter MAY be provided but then they MUST be equal.
- If a URL is not preregistered, a redirect_uri parameter MUST be provided and can be any value.
Failing these rules will result in an Authentication Failure.
In api.demo.openconext.org, the redirect URI preregistration is configured in ServiceRegistry, in the field coin:oauth:callback_url. There can be - comma separated - more then one redirect URI's.