Skip to content

Service Registration

To register a service (or client) in the Helmholtz AAI, you need to provide some necessary general information and some protocol specific information.

There is a testing instance!

Note that you can test the registration of your service(s) also on a testing/development instance. In that case, replace all of the following URLs by https://login-dev.helmholtz.de.

Service Registration depending on protocol

OAuth2/OIDC service

If you want to register an OAuth2/OIDC service, you can do this yourself:

  1. Browse to the Helmholtz AAI oauth home endpoint.
  2. Click on “No account? Sign up.” in the upper right corner.
    • Make sure that you are not logged in, otherwise the link is not displayed.
  3. In next menu select “Oauth2/OIDC client Registration” which is the first item.
  4. Fill in all necessary information.
    • The username is the client ID and the password is the client secret.
    • The OAuth client name will be the name displayed at the user’s home endpoint. This can be relevant when changing consent settings.
    • Use the Comments field to provide special needs, like public client for Single-Page-Application.
  5. By submitting the request, the AAI administrators are informed about your request and will review it.
  6. The client can not be used unless it was accepted by the AAI administrators.

SAML service

Self registration of SAML services, however, is not possible. You need to contact us and provide all of the information above. The AAI team will prepare the integration and come back to you to finish the integration.

Information needed to register the service, please provide this in your mail:

  • Service name
  • Service description
  • URL to data privacy statement
  • Service administrative contact (list preferred)
  • Service security contact (list preferred)
  • Site security contact (your local CERT)
  • Further protocol specific information (see subsection)
  • Postal adress of the organisation, providing the service
  • Entity ID
  • Return URL
  • Client Logo (Link to a png file)

Policies and security

For policy reasons you MUST provide:

  • Service Security Contact: this contact MUST be able to provide information about user logins to the security people in case of a security incident. This contact is invited to register at the Infrastructure Security Point described in the Security Incident Response.
  • Privacy Policy: This is a legal requirement. Luckily we do have a GDPR compliant PP template into which you only have to insert the specifics of your service.

Further, you MAY provide:

  • A custom Service Access Policy where you can specify user requirements for accessing the service, such as supported VOs and assurance levels.
    • No specific format is required, however you may adopt the template / PDF version.
    • Please make sure you are following the guidelines when expressing requirements for assurance. If you need additional user attributes besides those available, you may also specify them here, but it is up to you to negotiate any bilateral agreements that might be required.
    • It is up to you to ensure that the users of your service are aware of and agree to abide by any applicable service AUPs. Helmholtz AAI doesn’t provide any means to assist with that. However, the upcoming Helmholtz Cloud will provide additional functionality like this (and others), thus you may consider to apply for onboarding of your service to the Helmholtz Cloud.

Additionally, you need to accept and abide by the following policies:

Further information and endpoints

The mandatory information about the Helmholtz AAI IdP are:

The mandatory URLs of the Helmholtz AAI are:

Token revokation

The path /revoke can be used to revoke an access token which was previously issued. This endpoint is implemented according to the RFC 7009, with the following Unity specifics:

  • The token_type_hint is a mandatory argument, must be always provided (in RFC it is optional). The allowed values are access_token and refresh_token.
  • The endpoint access is authorized implicitly by providing a valid token to be revoked. The client_id must be always given.

Typical usage:

1
2
3
4
5
POST /.../revoke HTTP/1.1
Host: ...
Content-Type: application/x-www-form-urlencoded

token=45ghiukldjahdnhzdauz&client_id=oauth-client&token_type_hint=refresh_token