Skip to content

Home

Jump to bottom
arun-babu edited this page Apr 10, 2020 · 7 revisions

[ India Urban Data eXchange ]

Authentication, Authorization, and Accounting (AAA) server

1. Introduction

Welcome to the IUDX Authentication, Authentication, and Accounting (AAA) server.

This server serves the IUDX AAA REST APIs which can be called by:

  1. Data providers (the resource owners)
  2. Data consumers (users who wish to access one or more data provider's data)
  3. Resource servers (which hosts the data provider's data)

through HTTPS (using a valid client-side X.509 certificate).

2. Setup

Setup

[Note] In the above setup, the Resource server administrator and the Data provider may also be the same person.

3. Data access flow

Flow

4. APIs

The Auth APIs expect the METHOD to be POST.

Inputs/outputs if any, are expected to be in JSON.

And returns:

  1. 200 on success
  2. 400 on bad request
  3. 403 on unauthorized request

On exceptions:

  1. 402 on payment required (due to insufficient credits)
  2. 429 on too many requests
  3. 500 on internal error

Below are the list of Auth APIs.

  1. Get an access token (to be called by data consumers):

    /auth/v1/token

  2. Set access control polcies (to be called by data providers):

    /auth/v1/acl/set

  3. Append to existing access control policies (to be called by data providers):

    /auth/v1/acl/append

  4. Get the current access control policies (to be called by data providers):

    /auth/v1/acl

  5. Validate an access token (to be called by resource servers):

    /auth/v1/token/introspect

  6. Revoke tokens (can be called by both data providers and consumers):

    /auth/v1/token/revoke

  7. Revoke all tokens for a given certificate (can be called by both data providers and consumers):

    /auth/v1/token/revoke-all

  8. Audit tokens (can be called by both data providers and consumers):

    /auth/v1/audit/tokens

  9. Add a consumer to a group (to be called by a data provider):

    /auth/v1/group/add

  10. Delete a consumer from a group (to be called by a data provider):

    /auth/v1/group/delete

  11. List current consumers in a group (to be called by a data provider):

    /auth/v1/group/list

  12. Get the user's certificate details (can be called by any user):

    /auth/v1/certificate-info

5. Authentication

All APIs require a valid client-side certificate (X.509).

Data providers and consumers must have a valid emailAddress field in the certificate.

Where as, the resource server's certificate must have a valid hostname (FQDN) as the Common Name (CN). Also, for a resource server, the hostname in the certificate must match with the IP from where the API is being called.

To get a certificate, please visit any of the following certificate authorities (CA):

  1. IUDX certificate authority : https://ca.iudx.org.in
  2. Any licensed CA in India : http://cca.gov.in/licensed_ca.html
  3. Any standard trusted CA : List of trusted certificate authorities

Please note that: as of now, certificates issued by CAs other than IUDX CA will be considered as:

  • class-1 for resource servers.
  • class-2 for consumers.

If you wish to get a class-3 or above certificate, please use the IUDX CA or your organization's IUDX-subCA.

6. Certificate classes

There are 5 classes of certificates:

  • class-1: Can only be used by resource servers to validate/introspect their tokens. They can only be used to call the /auth/v1/token/introspect API.

  • class-2: Can be used by a data consumer to request access to protected data. They can only be used to call the /auth/v1/token API.

  • class-3: Can be used by a data consumer to request access to protected data. Can be used by a data provider to set access control policies and create/manage catalog entries.

  • class-4: Can be used by a data consumer to request access to private data.

  • class-5: Can be used by a data consumer to request access to confidential data.

7. Source code and SDKs

The source code of the AAA server is available at : https://github.com/iudx/iudx-auth-server

The python SDK (pyIUDX) to call the AAA APIs is available at : https://github.com/iudx/pyIUDX

8. For general queries, please contact us at

https://www.iudx.org.in/#contact-container

9. For technical and security issues, please contact : Arun Babu

[ Contact ]

Clone this wiki locally