Skip to content

API

Jump to bottom
Okke Harsta edited this page Jun 11, 2023 · 12 revisions

External API

The eduBadges API is protected with OpenID Connect. For the PoC we will start with the Auth2.0 client_credentials flow. The SIS must be added as a Relying Party with the client_credentials grant type and the correct scope: edubadges.nl/sis

sequenceDiagram
    participant Relying Party
    participant OIDC-NG
    participant eduBadges
    Relying Party->>OIDC-NG: Token URL
    Note right of Relying Party: client_id & secret
    OIDC-NG->>Relying Party: Code
    Relying Party->>OIDC-NG: Token endpoint
    Note right of Relying Party: Backend channel
    OIDC-NG->>Relying Party: JWT token
    Relying Party->>eduBadges: Direct award API POST
    Note right of Relying Party: BadgeClass entity_id, EPPN students
    Note right of eduBadges: Bearer token
    eduBadges->>OIDC-NG: Introspect token
    OIDC-NG->>eduBadges: Token client information
    eduBadges->>eduBadges: Lookup institution
    Note right of eduBadges: Lookup admin user of the institution
    eduBadges->>eduBadges: Direct awarding
    eduBadges->>Relying Party: Response status
    Relying Party->>Relying Party: User feedback
Loading

If we decide that we want personal bearer tokens, then a user must obtain this using the authorisation flow.

sequenceDiagram
    participant Relying Party
    participant OIDC-NG
    participant EB
    participant Institution IdP
    participant eduBadges
    Relying Party->>OIDC-NG: Authorization URL
    OIDC-NG->>EB: SAML request + WAYF
    EB->>Institution IdP: SAML request
    Institution IdP->>EB: SAML response
    EB->>OIDC-NG: SAML response
    OIDC-NG->>Relying Party: Code
    Relying Party->>OIDC-NG: Token endpoint
    Note right of Relying Party: Backend channel
    OIDC-NG->>Relying Party: Access token
    Relying Party->>eduBadges: Direct award API POST
    Note right of Relying Party: Course identifier, EPPN students
    Note right of eduBadges: Bearer token
    eduBadges->>OIDC-NG: Introspect token
    OIDC-NG->>eduBadges: Token user information
    eduBadges->>eduBadges: Lookup user
    Note right of eduBadges: Validate user permissions
    eduBadges->>eduBadges: Direct awarding
    eduBadges->>Relying Party: Response status
    Relying Party->>Relying Party: User feedback
Loading

To issue direct awards the Relying Party - a.k.a. SIS - will need to provide the entity_id to lookup the Badgeclass. The entity_id will be stored in the SIS. When an administrator looks up the Badgeclass in eduBadges then the entity_id can be copied to the clipboard in the Badgeclass detail page.

sequenceDiagram
    participant SIS
    participant eduBadges
    eduBadges->>eduBadges: Details Badgeclass
    Note right of eduBadges: Copy the entity_id
    SIS->>SIS: Store the entity_id in the SIS
Loading
Clone this wiki locally