Skip to content

Commit

Permalink
Merge pull request #363 from ThorodanBrom/docs
Browse files Browse the repository at this point in the history 
Draft first version of auth documentation
  • Loading branch information
@mahimatics
mahimatics authored Nov 14, 2024
2 parents ab20209 + 4ba874f commit 65fdf32
Show file tree
Hide file tree
Showing 7 changed files with 403 additions and 3 deletions.
15 changes: 12 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,23 @@


![IUDX](./readme/images/iudx.png)
# India Urban Data eXchange (IUDX) Authentication, Authorization, and Accounting (AAA) Server
# DX Authentication, Authorization, and Accounting (AAA) Server

IUDX-AAA is the Authentication, Authorization, and Accounting server for accessing [IUDX](https://www.iudx.org.in) services.
DX-AAA is the Authentication, Authorization, and Accounting server for accessing [DX](https://www.iudx.org.in) services.

<p align="center">
<img src="./readme/images/aaa_overview.png">
<img src="./readme/images/cdpg.png">
</p>

## Features

- Register for [roles](./readme/terms.md#roles)
- Get [DX access tokens](./readme/terms.md#tokens) to consume resources
- Manage [client credentials](./readme/terms.md#client-credentials)
- Manage [delegations](./readme/terms.md#delegations)
- Register [resource servers](./readme/terms.md#resource-servers) and manage [APDs](./readme/terms.md#apds)
- Search for users registered on the DX

## Get Started

### Prerequisite - Make configuration
Expand Down
122 changes: 122 additions & 0 deletions readme/config.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
# Configuration

Please refer to [config-example.json](/configs/config-example.json) for a sample configuration file.

## Main Values

| Value | Type | Example| Description |
| -------|----- | -------|----- |
| `version` | Float | |The version number |
| `zookeepers` | JSON Array of strings | |? |
| `clusterId` | String | ? |
| `options` | JSON Object | A collection of JSON objects that verticle configs can choose to use using the `required` array |
| `modules` | JSON Array of JSON objects | Verticle-specific configurations

## `options`

`options` comprises of a set of configurations organized in JSON objects that verticles can choose to add to their config. Each verticle config has a `required` array, where they can add a list of `options`. These configurations will get merged into the verticle config before the config is deployed. This mechanism avoid repeating the same config across each verticle.

| Value | Type | Example | Description |
| -------|----- | --------|---- |
| `postgresOptions` | JSON Object | {...}| Postgres connection related options |
| `commonOptions` | JSON Object | {...}|Common or server-specific options |
| `keycloakOptions` | JSON Object| {...}|Keycloak related options |
| `jwtKeystoreOptions` | JSON Object | {...}|JWT-signing keystore related options|

### `postgresOptions`

| Value | Type | Example |Description |
| -------|----- | -------|----- |
| `databaseIP` | String | `database.iudx.io`/`192.186.0.1` |The IP/hostname of the Postgres instance |
| `databasePort` | String | `5432` |The port number of the Postgres instance |
| `databaseName` | String | `database` |The name of the DB being used in the Postgres instance |
| `databaseSchema` | String | `schema` |The name of the DB schema being used in the Postgres instance|
| `databaseName` | String | `name` |The name of the DB user used to connect to the Postgres instance |
| `databasePassword` | String | `password` |The password of the DB user used to connect to the Postgres instance |

### `commonOptions`

| Value | Type | Example |Description |
| -------|----- | --------|---- |
| `cosDomain` | String | |The domain name used by the COS |
| `cosAdminUserId` | String | |The DX keycloak user ID of the COS Admin user |

### `keycloakOptions`
| Value | Type | Example |Description |
| -------|----- | -------|----- |
| `keycloakRealm` | String | `realm` | The Keycloak realm configured for the DX |
| `keycloakUrl` | String | `https://keycloak.dx.org.in/auth` | The Keycloak server URL in the format `{{protocol}}://{{keycloakHost}}:{{keycloakPort}}/auth` |
| `keycloakAdminClientId` | String | `keycloak-admin` | The client ID of the Keycloak client created for the AAA server |
| `keycloakAdminClientSecret` | String | `<UUID/Base64 string 32 characters long>` | The client secret for the Keycloak client created for the AAA server|
| `keycloakAdminPoolSize` | String | `10` | The number of API clients that can be created in a client pool to connect with Keycloak and make requests|
| `keycloakJwtLeeway` | Integer | `90` | The leeway for the Keycloak JWT token in seconds. The leeway accounts for clock skew on the AAA server when checking if a token has expired (`exp`) or when a token is valid (`iat`/`nbf`)|

### `jwtKeystoreOptions`

| Value | Type | Example |Description |
| -------|----- | --------|----- |
| `keystorePath` | String | `configs/keystore.jks` | The path to the keystore used to sign AAA tokens |
| `keystorePassword` | String | `password`| The password of the keystore |

## `modules`

`modules` is a JSON array comprising of all the individual verticle configs.

### Options common to all verticle configs

| Value | Type | Example |Description |
| -------|----- | --------|----- |
| `id` | String | `iudx.aaa.server.policy.PolicyVerticle` | The package name of the verticle to be deployed |
| `verticleInstances` | Integer | `1`| The number of instances of the verticle to be deployed |
| `required` | JSON Array | `["postgresOptions"]`| The config blocks from the `options` object to be merged with this verticle's config. See the example config for verticle specific values |
| `poolSize` | String | `5`| The size of the Postgres DB pool created for this verticle|

### Verticle-specific config options

#### PolicyVerticle

| Value | Type | Example |Description |
| -------|----- | --------|----- |
| `catalogueOptions` | JSON Object | {...} | JSON object containing DX catalogue information to fetch data from the catalogue |

##### `catalogueOptions`

| Value | Type | Example |Description |
| -------|----- | --------|----- |
| `catServerHost` | String | `api.catalogue.dx.com` | The DX catalogue URL |
| `catServerPort` | String | `8080`| The DX catalogue port|
| `catServerBasePath` | String | `/dx/cat/v1`| The base path used in DX catalogue APIs |

#### RegistrationVerticle

| Value | Type | Example |Description |
| -------|----- | --------|----- |
| `serversOmittedFromRevoke` | JSON Array of strings | `["rs.dx.org"]` | Servers that will not be intimated about token revocation |

#### ApdVerticle

| Value | Type | Example |Description |
| -------|----- | --------|----- |
| `webClientTimeoutMs` | Integer| `3000` | Timeout in milliseconds for APD `/verify` API call |

#### AuditingVerticle

| Value | Type | Example |Description |
| -------|----- | -------|----- |
| `auditingDatabaseIP` | String | `database.iudx.io`/`192.186.0.1` |The IP/hostname of the ImmuDB instance |
| `auditingDatabasePort` | String | `5432` |The port number of the ImmuDB instance |
| `auditingDatabaseName` | String | `database` |The name of the DB being used in the ImmuDB instance |
| `auditingDatabaseSchema` | String | `schema` |The name of the DB schema being used in the ImmuDB instance|
| `auditingDatabaseName` | String | `name` |The name of the DB user used to connect to the ImmuDB instance |
| `auditingDatabasePassword` | String | `password` |The password of the DB user used to connect to the ImmuDB instance |
| `auditingDatabaseTableName` | String | `password` |The table in the ImmuDB instance where data will be stored|
| `auditingPoolSize` | Integer| `10` |The number of connections in the pool used to connect to the ImmuDB instance |

#### ApiServerVerticle

| Value | Type | Example |Description |
| -------|----- | -------|----- |
| `httpPort` | Integer | `8443` |The port at which the AAA server will run|
| `serverTimeoutMs` | Integer | `5000` | Default timeout for any API call made to the AAA server |
| `corsRegexString` | String | `*` |A regex string used for CORS validation|

Binary file added readme/images/aaa-soln.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added readme/images/cdpg.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
87 changes: 87 additions & 0 deletions readme/setup.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
# Setup

## Steps
- Setup the key used to sign JWT tokens
- Set up the database using Flyway
- Set up Keycloak
- Create COS Admin
- ImmuDB setup

### JWT signing key setup

The Current Implementation of JWT in iudx-aaa-server is based on Vert.x `vertx-auth-jwt` library. The Vert.x JWT implementation or any other Vertx security implementations generally requires a creation/implementation of security interface AuthenticationProvider, In JWT case it is JWTAuth as Authentication Provider

There are multiple types of signature methods used for signing JWT, and each of them either requires buffer or PKI or certificates, or jks for instantiating the Authentication Provider in Vertx.

The current implementation is based on asymmetric key algorithm **ECDSA** (Elliptic Curve Digital Signature Algorithm), and the signature method is **ES256**.

The Authentication Provider looks for aliases in the provided Keystore to verify and sign the generated JWT. The keystore and keypair should also be generated and signed using same algorithm which is required to sign and verify the JWT. For Signature algorithm ES256, the keystore alias is ES256.

The Keytool command to generate ECDSA keystore keypair is:

```
keytool -genkeypair -keystore keystore-ec.jks -storetype jks -storepass secret -keyalg EC -alias ES256 -keypass secret -sigalg SHA256withECDSA -dname "CN=,OU=,O=,L=,ST=,C=" -validity 360 -deststoretype pkcs12
```

The keystore path and the keystore password should then be added to the server config.

### Flyway Database setup

Flyway is used to manage the database schema and handle migrations. The migration files are located at [src/main/resources/db/migrations](src/main/resources/db/migrations). The following pre-requisites are needed before running `flyway`:
1. An admin user - a database user who has create schema/table privileges for the database. It can be the super user.
2. An auth user - a database user with no privileges; this is the database user that will be configured to make queries from the server
(e.g. `CREATE USER auth WITH PASSWORD 'randompassword';`)

[flyway.conf](flyway.conf) must be updated with the required data.
* `flyway.url` - the database connection URL
* `flyway.user` - the username of the admin user
* `flyway.password` - the password of the admin user
* `flyway.schemas` - the name of the schema under which the tables are created
* `flyway.placeholders.authUser` - the username of the auth user

Please refer [here](https://flywaydb.org/documentation/configuration/parameters/) for more information about Flyway config parameters.

After this, the `info` command can be run to test the config. Then, the `migrate` command can be run to set up the database. At the `/iudx-aaa-server` directory, run

```
mvn flyway:info -Dflyway.configFiles=flyway.conf
mvn flyway:migrate -Dflyway.configFiles=flyway.conf
```

### Keycloak setup

The AAA server uses [Keycloak](https://www.keycloak.org/about.html) to manage user identity. Please refer [here](https://www.keycloak.org/docs/latest/server_admin/#core-concepts-and-terms) to become familiar with Keycloak terminology.

#### Realm Creation

- A new realm must be configured. Follow the steps outlined [here](https://www.keycloak.org/docs/latest/server_admin/#_configuring-realms) to create a new realm.

- Once the new realm has been created, `Email as username` and `Login with email` must be configured in the `Login` tab of the `Realm settings` panel for the new realm


#### Auth Server client creation

The AAA server requires a client to be configured that would allow the server to interact with Keycloak. The client would be able to search for users on the configured Keycloak realm, as well as validate OIDC tokens issued by Keycloak from that realm.

- Follow the steps outlined [here](https://www.keycloak.org/docs/latest/server_admin/#proc-creating-oidc-client_server_administration_guide) to create a new client. Ensure that:
- In Capability config `Client authentication` is turned on, `Authorization` is off, and in `Authentication flow`, **only** `Service accounts roles` is turned on
- Once the client has been created successfully, fetch the client secret of the client by following the steps outlined [here](https://www.keycloak.org/docs/latest/server_admin/#_client-credentials). The client ID is the name of the client itself.
- This client must have the capability to search for users and realms (In the `Service account roles` tab, click `Assign Role` -> choose `Filter by clients` -> search for `realm-management` -> select `view-users` and click `Assign`)


#### COS Admin User creation

The COS Admin user can perform certain tasks in the COS. The Keycloak user ID of this user must be placed in the AAA config in order for the server to recognize that the particular user has the role of COS Admin.

- Create a user on Keycloak by following the steps [here](https://www.keycloak.org/docs/latest/server_admin/#proc-creating-user_server_administration_guide). Copy the user ID of the user once created.
- Set a **permanent** password for the user by following the steps [here](https://www.keycloak.org/docs/latest/server_admin/#ref-user-credentials_server_administration_guide).

The copied user ID will later be used in the config.

### ImmuDB setup

ImmuDB is used to record audit logs of all operations done on the AAA server.

- Create a table in ImmuDB with schema as specified [here](https://github.com/datakaveri/dx-resource-server/blob/5.5.0/src/main/resources/db/migration/V4_0__Add-tables-in-postgres-for-metering.sql#L41-L50)


56 changes: 56 additions & 0 deletions readme/solution-architecture.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Solution Architecture

<p align="center">
<img src="./images/aaa-soln.png" width="1000"></img>
</p>

## Vert.x

The AAA server has been written in the [Vert.x](https://vertx.io/) Java framework. All major components of the server have been divided into [Vert.x verticles](https://vertx.io/docs/vertx-core/java/#_verticles).

## Internal Server Architecture

The various components of the AAA server are organized into Vert.x verticles based on functionalities and APIs. These verticles are exposed as services and rely on service discovery to discover each other. See [Vert.x Service Proxy](https://vertx.io/docs/vertx-service-proxy/java/) and [Vert.x cluster managers](https://vertx.io/docs/vertx-core/java/#_cluster_managers) for more information.

A basic description of each service is as follows:

- **Registration Service** : Handles APIs related to role management, user management and client credentials management.
- **Admin Service** : Handles APIs related to resource server registration and provider approval.
- **Token Service** : Handles all APIs related to tokens (creation, revocation, introspection etc.)
- **Policy Service** : Handles APIs related to delegation. Also has internal methods for resource access decisions.
- **APD Service** : Handles APIs related to APD management. Also has internal methods for AAA-to-APD interactions for resource access decisions.
- **Auditing Service** : Handles auditing of successful API calls in the auditing database.

## External Dependencies

### DX Catalogue Server

The AAA server depends upon the DX catalogue server for issuing tokens to obtain information about a requested resource. The main APIs used by the AAA server are the [Entity - Get Item API](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/datakaveri/iudx-catalogue-server/master/docs/openapi.yaml#tag/Entity/operation/get%20item) and the [Relationship - Get Related Entity API](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/datakaveri/iudx-catalogue-server/master/docs/openapi.yaml#tag/Relationship/operation/get%20related%20entity)

### Identity Server - Keycloak

[Keycloak](https://www.keycloak.org/) is used for identity management i.e. SSO login, password management, user information management etc. in the DX ecosystem. Most AAA APIs require Keycloak token authorization, which makes it necessary for users to be registered on Keycloak to interact with the AAA server.

Since Keycloak stores user information, the AAA server makes use of the Java [Keycloak Admin Client](https://www.keycloak.org/securing-apps/admin-client) to fetch user information like names and email addresses and to search for users based on email addresses or user IDs. Refer to [KcAdmin.java](src/main/java/iudx/aaa/server/registration/KcAdmin.java) to see how the AAA server interacts with Keycloak.

### PostgreSQL

The AAA server makes use of the [PostgreSQL](https://www.postgresql.org/) relational database to store all information. The tables in PostgreSQL are managed using migrations with [Flyway](https://www.red-gate.com/products/flyway/community/) and migrations are present in `src/main/resource/db/migration`

#### Exploring the PostgreSQL Schema

To explore the different tables and relations in the schema, please use a tool like [SchemaSpy](https://schemaspy.org/) on an existing database where all Flyway migrations have been applied.

### ImmuDB

[ImmuDB](https://immudb.io/) is used as the database to store all successful API calls for auditing purposes.

## Monitoring and Logging

[Micrometer metrics](https://vertx.io/docs/vertx-micrometer-metrics/java/) are exposed by the AAA server for monitoring. Prometheus and Grafana are used to collect and display metrics respectively.

[Log4J](https://logging.apache.org/log4j/2.x/index.html) is used for logging. The logging configuration can be found [here](src/main/resources/log4j2.xml). [Loki](https://grafana.com/docs/loki/latest/) and [Grafana](https://grafana.com/oss/grafana/) are used to collect and display logs respectively.

## Deployment

Docker images of the AAA server are available.
Loading

0 comments on commit 65fdf32

Please sign in to comment.