Clients

OpenID Connect clients

The OpenConext-oidc makes it possible for Service Providers - who want to join the SURFnet federation, but do not want to implement / use SAML for the user authentication - to use the OpenID Connect protocol to connect to the SURFnet federation.

We distinguish two types of client:

• Service Providers who only need an identifier of the user in order to provision the user locally
• Service Providers who need more then only the identifier (e.g. name, email etc)

ID Token

The first type only needs to obtain an ID Token which contains the unique identifier of the user - e.g. the sub. This can be achieved by making an authorize call to the OIDC endpoint:

https://oidc.surfconext.nl/authorize?response_type=id_token&client_id=client_id&scope=openid&redirect_uri=redirect_uri

The Service Provider (e.g. OIDC client) will have received the client_id out-of-band. The redirect_uri must equals the redirect_uri that was communicatied out-of-band with SURFnet. The response - after successful authentication of the user - contains the id_token in the fragment part of the url:

https://redirect_uri#id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6Im9pZGMifQ.eyJleHAiOjE0NTc0MzQ1NzEsInN1YiI6IjFjZmJiNWEzNzU2ODk1MmI5YjcwNWJiZjljYzUyOWQ0ODM4OTIwMDYiLCJhdWQiOiJodHRwc0BcL1wvYXV0aHotcGxheWdyb3VuZC50ZXN0LnN1cmZjb25leHQubmwiLCJpc3MiOiJodHRwczpcL1wvb2lkYy50ZXN0LnN1cmZjb25leHQubmxcLyIsImp0aSI6Ijc3Y2JiZTdkLTAxNmEtNDQ0OC1hMjQ0LTE4Njk4Yzk1OTBiMiIsImlhdCI6MTQ1NzQzMzk3MSwia2lkIjoib2lkYyJ9.Jl6WTizrmFv05lQY69Q6rL6hFx39U7M6Gp3sdyMgzP1yndJU7IGvqrgB3ikTvdzfoZWJjfIrrTM5BrXZMXI4Z4-BrvnTj4bS99s4KRBGgLErW6GC4M8zo9lpo_Lq5nRnmOHau13oJC6jnOsvoUds_R1U_sUWovgyEnUGfk-nmZIlodollM7AqaYYLq-5hCUp88ZEGMAVIXKA51fgePT9Pg_-GGz_sEivTQdUPIwiLdd6YFxXJ88txdI5ieiTfRnlY49AZpujF7F_NTXYDIMD5pJa8qF7DZjxD7GScdrB7iOz3IIGADC5E6SzxuGIjNs7D4M5UQ4LK2l7AeLJ9ZQKJw

The id_token is a JSON Web Token and can be parsed using a variety of libraries. See https://jwt.io/ for an overview. The parsed id_token looks like this:

{
  "payload" : {
    "sub" : "1cfbb5a37568952b9b705bbf9cc529d483892006",
    "aud" : [ "https@//authz-playground.test.surfconext.nl" ],
    "kid" : "oidc",
    "iss" : "https://oidc.test.surfconext.nl/",
    "exp" : 1457434571000,
    "iat" : 1457433971000,
    "jti" : "77cbbe7d-016a-4448-a244-18698c9590b2"
  },
  "header" : {
    "kid" : "oidc",
    "alg" : "RS256"
  }
}

The sub is the unique identifier.

Access Token

The Service Providers who need more then only the unique identifier need to obtain an access_token. First authorize the user:

https://oidc.surfconext.nl/authorize?response_type=code&client_id=client_id&scope=openid&redirect_uri=redirect_uri

The Service Provider (e.g. OIDC client) will have received the client_id out-of-band. The redirect_uri must equals the redirect_uri that was communicatied out-of-band with SURFnet. The response - after successful authentication of the user - contains a code in the query parameter:

https://redirect_uri?code=AokpF3

This code can be used to obtain an access_token by posting a HTTP request to https://oidc.surfconext.nl/token. The method needs to have the following headers:

• Authorization: Basic client_id:secret (base64 encoded)
• Content-Type: application/x-www-form-urlencoded

The Body needs have the following form key/values:

• code=AokpF3 (the code from the authorize response)
• grant_type=authorization_code
• redirect_uri=https://redirect_uri (the redirect_uri used in the authorize request)

The response of the POST contains the access_token in the body:

{
  "access_token" : "eyJhbGciOiJSUzI1NiIsImtpZCI6Im9pZGMifQ.eyJleHAiOjE0NTc0Mzg2NjMsImlzcyI6Imh0dHBzOlwvXC9vaWRjLnRlc3Quc3VyZmNvbmV4dC5ubFwvIiwiYXVkIjoiaHR0cHNAXC9cL2F1dGh6LXBsYXlncm91bmQudGVzdC5zdXJmY29uZXh0Lm5sIiwianRpIjoiZjAyYjdjOGMtM2MzYS00Y2M2LTk3OTktMjMxMWJlMjY1MDE4IiwiaWF0IjoxNDU3NDM1MDY0fQ.XW-7Gf2-oJrBW0-2gXfEW1Za3auoGHiLd_2hWJ4hUj8_NtzqzJW-VMpwvUVDI_Ve-Lh8JBT8Bf5UZ9c3xGMV00dCB75YxTQ3C39xzMZ2qIWkDF5daHI4ncaJo4YGPIja9osUGIO2Oh7jjDuv84j9l6A2qcUcm06QPgGy-cIjMk4lOX4sXiaFJS2vMsOS5mOxmJu_G71uvFwLKUvJh7gXeeil2DMNKNRkEkOIPa5RWVaAFta8x-jHalxQEEesKb84hyo3AuOm2mUn0k_Kv22vy5uGLIEO4RmGgPncnj8OIjWSwIjHZmewM_YOgfevbpX1vJcL1s7wamJGCkdcXd4z9g",
  "token_type" : "Bearer",
  "expires_in" : 3599,
  "scope" : "openid"
}

The access_token can be used to retrieve all the user info:

https://oidc.surfconext.nl/userinfo

The call to the userinfo endpoint needs to minimally have the following headers:

• Authorization: bearer access_token (the access_token from the authorization response)
• Content-Type: application/json

The response is JSON and contains all the information the Service Provider may access (it can and will be restricted depending on the institution of the user).

{
  "sub" : "1cfbb5a37568952b9b705bbf9cc529d483892006",
  "name" : "John Doe",
  "preferred_username" : "admin",
  "given_name" : "John",
  "family_name" : "Doe",
  "nickname" : "admin",
  "email" : "[email protected]",
  "schac_home_organization" : "example.com",
  "edu_person_principal_name" : "[email protected]",
  "edu_person_targeted_id" : "1cfbb5a37568952b9b705bbf9cc529d483892006",
  "edu_person_scoped_affiliations" : [ "teacher", "professor" ],
  "is_member_ofs" : [ "urn:collab:org:surf.nl" ],
  "uids" : [ "admin" ]
}