for businessplayground
openid
eapi
rp management api

RP Management API

Overview

This API is intended for Relying Parties managing their own attributes and their users.

It is not an API to manage any attribute on the user, only attributes the RP actually owns, like an employee number, subscription number or similar. RPs will never be able to administer attributes they do not own.

Terms

  • Relying Party (RP) - The application consuming the API.
  • DServ - Idfyed cloud service implementing the API.

Prerequisites

Since the management API is secured, it is not possible to use the API until the following artifacts has been received from Idfyed:

  • an API unique URL (see Changelog for URLs including versions):

    • Test system used for integration and test:

      https://test.idfyed.com/rp-mgmt/attribute/<version>/<customerName>/<userId>

    • Production system used for the production application.:

      https://api.idfyed.com/rp-mgmt/attribute/<version>/<customerName>/<userId>

    • credentials to be able to access the REST API.

Flow

  1. RP calls backend API with action, customerName, userId and attributes.
  2. A HTTP 204 status is returned.
  3. Next time user starts the Idfyed app
    1. Idfyed app fetches information.
    2. Show an information message to the user that the RP wants to perform the action specified by the transaction.
    3. User accepts change.
    4. User is updated.

API

Update API

The RP should do a POST to the specified URL according to documentation.

URL

The URL for the API contains:

  • customerName: name of customer received from Idfyed
  • userId: the userId presented to RP when authenticating using one of the authentication protocols available, like EAPI.

Request body

The body shall be sent json encoded with ContentType set to application/json.

Parameters marked with * are mandatory.

Parameter Name Type Description Version
action* String What action to perform on the user. ADD and REMOVE are valid values. 1.0
attributes* Array Array of attributes. 1.0
attributes[].name* String Name of attribute. 1.0
attributes[].value* String Value of attribute. 1.0

Example request

{
  "action": "ADD",
  "attributes": [
    {
      "name": "acmeId",
      "value": "234654-2455423"
    },
    {
      "name": "acmeTitle",
      "value": "Wizard"
    }
  ]
}

Output

There is not data returned from the API, just a status code.

Success

A successful request returns the HTTP status code 204.

Fail

All other return values are considered errors, and can be interpreted according to RFC 1945.

Authentication

The API call is authenticated using HTTP Basic authentication as specified in RFC 1945. Credentials are provided by Idfyed.

Changelog

RP-mgmt v1.0

First version.

v1.0 URLs:

Test system used for integration and test:

https://test.idfyed.com/rp-mgmt/attribute/v1.0/<customerName>/<userId>

Production system used for the production application:

https://api.idfyed.com/rp-mgmt/attribute/v1.0/<customerName>/<userId>

References

  • RFC 1945 Hypertext Transfer Protocol -- HTTP/1.0, T. Berners-Lee, R. Fielding, H. Frystyk, 1996