[ India Urban Data eXchange (IUDX) ]

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   (client/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

[Data access 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: 4. 402 on payment required (due to insufficient credits) 5. 429 on too many requests 6. 500 on internal error Below are the list of Auth APIs:
# Endpoint Description Can be called by Try it on browser
1 /auth/v1/token Request for an access token Data consumer link
2 /auth/v1/acl/set Set access control polcies Data provider link
3 /auth/v1/acl/revert Revert to previous access control policy Data provider link
4 /auth/v1/acl/append Append to existing access control polcies Data provider link
5 /auth/v1/acl Get the current list of access control policies Data provider link
6 /auth/v1/token/introspect Verify a token Resource server link
7 /auth/v1/token/revoke Revoke a list of tokens Both data providers and consumers link
8 /auth/v1/token/revoke-all Revoke all tokens associated with a certificate Both data providers and consumers link
9 /auth/v1/audit/tokens Audit tokens Both data providers and consumers link
10 /auth/v1/group/add Add a consumer to a group Data provider link
11 /auth/v1/group/delete Delete a consumer from a group Data provider link
12 /auth/v1/group/list List all valid members of a group Data provider link
13 /auth/v1/certificate-info Get user's certificate details Anyone link
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 [ barun AT iisc DOT ac DOT in ]