Skip to content

Releases: datakaveri/iudx-aaa-server

v5.6.0

15 Nov 06:02
65fdf32
Compare
Choose a tag to compare

Version Summary

Version Number : v5.6.0 [tag: v5.6.0]
Date: 15-November-2024

Projects / Repos Included in this release: DX AAA Server, DX Deployment and installation, DX's Documentation

Release Summary :

Data Exchange AAA Server v5.6.0 is released with the following enhancements

  • Included wiki with extended documentation for the following
    • Architecture
    • Usage guides
    • Configuration Mapping
    • Prerequisites
  • Updated Software Testing
    • Bug Fixes
  • Software License:

Test Reports:

Please find the release test details and reports here

API Docs

The api docs can be found here.

How to use the Release:

Prerequisite - Make configuration

  • Make a config file based on the template in ./configs/config-example.json
  • Setup the key used to sign JWT tokens
  • Modify the database url and associated credentials in the appropriate sections
  • Set up the database using Flyway
  • Set up Keycloak

JWT signing key setup

The Current Implementation of JWT in 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. 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 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 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

The database details should then be added to the server config.

Keycloak setup

The AAA server uses Keycloak to manage user identity. Please refer here to become familiar with Keycloak terminology.

  1. 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. This client must have the capability to search for users and realms (In Service account roles -> client roles -> realm-management -> add view-users to Assigned roles)

  2. Email as username needs to be configured in the Login tab of the Realm settings.

The Keycloak URL and realm information along with the client IDs and client secret information should then be added to the server config.

Docker based

  1. Install docker and docker-compose
  2. Clone this repo
  3. Build the images
    ./docker/build.sh
  4. Modify the docker-compose.yml file to map the config file you just created
  5. Start the server in production (prod) or development (dev) mode using docker-compose
    docker-compose up prod
  6. The server will be up on port 8080. To change the port, add httpPort:<desired_port_number> to the config in the ApiServerVerticle module. See configs/config-example.json for an example.

Maven based

  1. Install java 11 and maven
  2. Set Environment variables
export AUTH_URL=http://<auth-domain-name>
export LOG_LEVEL=INFO
  1. Use the maven exec plugin based starter to start the server
    mvn clean compile exec:java@aaa-server
  2. The server will be up on port 8080. To change the port, add httpPort:<desired_port_number> to the config in the ApiServerVerticle module. See configs/config-example.json for an example.

JAR based

  1. Install java 11 and maven
  2. Set Environment variables
export AUTH_URL=http://<auth-domain-name>
export LOG_LEVEL=INFO
  1. Use maven to package the application as a JAR
    mvn clean package -Dmaven.test.skip=true
  2. 2 JAR files would be generated in the target/ directory
    • iudx.aaa.server-cluster-0.0.1-SNAPSHOT-fat.jar - clustered vert.x containing micrometer metrics
    • iudx.aaa.server-dev-0.0.1-SNAPSHOT-fat.jar - non-clustered vert.x and does not contain micrometer metrics

Running the clustered JAR

Note: The clustered JAR requires Zookeeper to be installed. Refer here to learn more about how to set up Zookeeper. Additionally, the zookeepers key in the config being used needs to be updated with the IP address/domain of the system running Zookeeper.

The JAR requires 3 runtime arguments when running:

  • --config/-c : path to the config file
  • --hostname/-i : the hostname for clustering
  • --modules/-m : comma separated list of module names to deploy

e.g.

java -Dvertx.logger-delegate-factory-class-name=io.vertx.core.logging.Log4j2LogDelegateFactory -jar target/iudx.aaa.server-cluster-0.0.1-SNAPSHOT-fat.jar --host $(hostname) -c configs/config.json -m iudx.aaa.server.admin.AdminVerticle,iudx.aaa.server.token.TokenVerticle,iudx.aaa.server.registration.RegistrationVerticle,iudx.aaa.server.auditing.AuditingVerticle

Use the --help/-h argument for more information. You may additionally append an AUTH_JAVA_OPTS environment variable containing any Java options to pass to the application.

e.g.

$ export AUTH_JAVA_OPTS="-Xms128m -Xmx512m"
$ java $AUTH_JAVA_OPTS -jar target/iudx.aaa.server-cluster-0.0.1-SNAPSHOT-fat.jar ...

Running the non-clustered JAR

The JAR requires 1 runtime argument when running:

  • --config/-c : path to the config file

e.g.

java -Dvertx.logger-delegate-factory-class-name=io.vertx.core.logging.Log4j2LogDelegateFactory -jar target/iudx.aaa.server-dev-0.0.1-SNAPSHOT-fat.jar -c configs/config.json

Use the --help/-h argument for more information. You may additionally append an AUTH_JAVA_OPTS environment variable containing any Java options to pass to the application.

e.g.

$ export AUTH_JAVA_OPTS="-Xms128m -Xmx512m"
$ java $AUTH_JAVA_OPTS -jar target/iudx.aaa.server-dev-0.0.1-SNAPSHOT-fat.jar ...

License

With this release, all DX Softwares will be distributed under Apache 2.0 License

What's Changed

Full Changelog: v5.5.0...v5.6.0

v5.5.0

03 Apr 10:40
c1b25ba
Compare
Choose a tag to compare

Version Summary

Version Number : v5.5.0 [tag: v5.5.0]
Date: 03-April-2024

Projects / Repos Included in this release: IUDX AAA Server, IUDX Deployment and installation, IUDX's Documentation

Release Summary :

India Urban Data Exchange (IUDX) | AAA Server v5.5.0 is released with enhanced features.

Highlights:

  • Updated Software Client libraries
  • Updated Software Testing
    • Updated REST Assured based integration testing
    • Bug Fixes
  • Software License:

Test Reports:

Please find the release test details and reports here

API Docs

The api docs can be found here.

How to use the Release:

Prerequisite - Make configuration

  • Make a config file based on the template in ./configs/config-example.json
  • Setup the key used to sign JWT tokens
  • Modify the database url and associated credentials in the appropriate sections
  • Set up the database using Flyway
  • Set up Keycloak

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. 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 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 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

The database details should then be added to the server config.

Keycloak setup

The AAA server uses Keycloak to manage user identity. Please refer here to become familiar with Keycloak terminology.

  1. 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. This client must have the capability to search for users and realms (In Service account roles -> client roles -> realm-management -> add view-users to Assigned roles)

  2. Email as username needs to be configured in the Login tab of the Realm settings.

The Keycloak URL and realm information along with the client IDs and client secret information should then be added to the server config.

Docker based

  1. Install docker and docker-compose
  2. Clone this repo
  3. Build the images
    ./docker/build.sh
  4. Modify the docker-compose.yml file to map the config file you just created
  5. Start the server in production (prod) or development (dev) mode using docker-compose
    docker-compose up prod
  6. The server will be up on port 8080. To change the port, add httpPort:<desired_port_number> to the config in the ApiServerVerticle module. See configs/config-example.json for an example.

Maven based

  1. Install java 11 and maven
  2. Set Environment variables
export AUTH_URL=http://<auth-domain-name>
export LOG_LEVEL=INFO
  1. Use the maven exec plugin based starter to start the server
    mvn clean compile exec:java@aaa-server
  2. The server will be up on port 8080. To change the port, add httpPort:<desired_port_number> to the config in the ApiServerVerticle module. See configs/config-example.json for an example.

JAR based

  1. Install java 11 and maven
  2. Set Environment variables
export AUTH_URL=http://<auth-domain-name>
export LOG_LEVEL=INFO
  1. Use maven to package the application as a JAR
    mvn clean package -Dmaven.test.skip=true
  2. 2 JAR files would be generated in the target/ directory
    • iudx.aaa.server-cluster-0.0.1-SNAPSHOT-fat.jar - clustered vert.x containing micrometer metrics
    • iudx.aaa.server-dev-0.0.1-SNAPSHOT-fat.jar - non-clustered vert.x and does not contain micrometer metrics

Running the clustered JAR

Note: The clustered JAR requires Zookeeper to be installed. Refer here to learn more about how to set up Zookeeper. Additionally, the zookeepers key in the config being used needs to be updated with the IP address/domain of the system running Zookeeper.

The JAR requires 3 runtime arguments when running:

  • --config/-c : path to the config file
  • --hostname/-i : the hostname for clustering
  • --modules/-m : comma separated list of module names to deploy

e.g.

java -Dvertx.logger-delegate-factory-class-name=io.vertx.core.logging.Log4j2LogDelegateFactory -jar target/iudx.aaa.server-cluster-0.0.1-SNAPSHOT-fat.jar --host $(hostname) -c configs/config.json -m iudx.aaa.server.admin.AdminVerticle,iudx.aaa.server.token.TokenVerticle,iudx.aaa.server.registration.RegistrationVerticle,iudx.aaa.server.auditing.AuditingVerticle

Use the --help/-h argument for more information. You may additionally append an AUTH_JAVA_OPTS environment variable containing any Java options to pass to the application.

e.g.

$ export AUTH_JAVA_OPTS="-Xms128m -Xmx512m"
$ java $AUTH_JAVA_OPTS -jar target/iudx.aaa.server-cluster-0.0.1-SNAPSHOT-fat.jar ...

Running the non-clustered JAR

The JAR requires 1 runtime argument when running:

  • --config/-c : path to the config file

e.g.

java -Dvertx.logger-delegate-factory-class-name=io.vertx.core.logging.Log4j2LogDelegateFactory -jar target/iudx.aaa.server-dev-0.0.1-SNAPSHOT-fat.jar -c configs/config.json

Use the --help/-h argument for more information. You may additionally append an AUTH_JAVA_OPTS environment variable containing any Java options to pass to the application.

e.g.

$ export AUTH_JAVA_OPTS="-Xms128m -Xmx512m"
$ java $AUTH_JAVA_OPTS -jar target/iudx.aaa.server-dev-0.0.1-SNAPSHOT-fat.jar ...

License

With this release, all IUDX Softwares will be distributed under Apache 2.0 License

What's Changed

Read more

AAA Server v5.0.0

31 Oct 08:45
4da72b7
Compare
Choose a tag to compare

What's changed

The AAA Server v5.0.0 release incorporates changes for the server to adhere to the COS model.

Updates to existing APIs

  • Create User Profile POST /auth/v1/user/profile changed to Add roles POST /auth/v1/user/roles

  • Get User Profile or Search for User GET /auth/v1/user/profile changed to List User Roles GET /auth/v1/user/roles

  • Update User Profile - Add roles, regenerate client secret PUT /auth/v1/user/profile removed

  • Get Organization Details GET /auth/v1/organizations changed to Get Registered Resource Servers GET /auth/v1/resourceservers

  • Create Organization POST /auth/v1/admin/organizations changed to Create Resource Server - COS Admin POST /auth/v1/admin/resourceservers

  • Get Policies GET /auth/v1/policies removed

  • Delete Policies DELETE /auth/v1/policies removed

  • Create Policies POST /auth/v1/policies removed

  • Get Delegations GET /auth/v1/policies/delegations changed to GET /auth/v1/delegations

  • Delete Delegations DELETE /auth/v1/policies/delegations changed to DELETE /auth/v1/delegations

  • Create Delegations POST /auth/v1/policies/delegations changed to POST /auth/v1/delegations

  • List Access Requests GET /auth/v1/policies/requests removed

  • Create Access Requests POST /auth/v1/policies/requests removed

  • Update Access Requests PUT /auth/v1/policies/requests removed

  • Withdraw Access Requests DELETE /auth/v1/policies/requests removed

New APIs

  • Create Default Client Credentials GET /auth/v1/user/clientcredentials
  • Search for User - Trustee GET /auth/v1/user/search
  • Regenerate client credentials PUT /auth/v1/user/clientcredentials
  • Get Delegate Emails - Trustee GET /auth/v1/delegations/emails
  • Get public key in JWKS format GET /auth/v1/jwks

Deprecations

User and Role Management

  • The auth admin user has been deprecated and replaced with the COS Admin
  • Organization registration has been removed
  • Registration of trustee and delegate role has been removed
  • Domain-matching for emails during provider registration has been removed

Policy-related Functionalities

  • All policy and access request APIs have been deprecated
    • This functionality has been moved to a separate ACL Access Policy Domain server

Token Functionalities

  • Token requests for items at the resource group level (itemType:resource_group) has been deprecated
  • Token requests for the trustee role (role:trustee) has been deprecated

Access Policy Domain (APD) Functionalities

  • Creation of APDs by trustees has been deprecated
  • Update of APD status by trustees has been deprecated

Delegations

  • The auth delegate role has been deprecated

New Features

General

  • The JWT public key is now exposed as a standard JWKS endpoint at GET /auth/v1/jwks

User and Role Management

  • User roles are scoped to registered resource servers
  • Provider approval is now performed by the concerned Resource Server admin
  • Default client credentials are now obtained using the API GET /auth/v1/user/clientcredentials instead of being created during role registration

Delegations

  • Consumers are allowed to assign delegates
  • Delegates do not need to register for the delegate role, they only need to be registered on Keycloak
  • Delegations are scoped to a role and a resource server
  • Delegates of consumers and providers may now obtain tokens on behalf of their delegator for entities that their delegator has access to

Trustee Capabilities

  • Users who are trustees of active APDs can now use their client credentials:
    • to search for registered providers and consumers
    • to obtain email addresses of delegates associated with a registered provider or consumer

Admin and Access Policy Domain (APD) Functionalities

  • Resource server creation is now performed by the COS Admin
  • APD creation and APD status update is now performed by the COS Admin
  • APDs are no longer in pending state when created. They are directly in an active state

Token Functionalities

  • COS Admins may get identity tokens for the COS item type (itemType:cos) and COS admin role (role:cos_admin)
  • Identity tokens for consumers and providers are now created only if the user has the role approved for the requested resource server
  • All token requests for resource items (itemType:resource) will result in an Access Policy Domain verification, i.e. the AAA server will interact with the APD associated with the resource. The AAA server will issue a token only if the APD responds with a success response

Enhancement

  • Miscellaneous library upgrades and bug fixes

Testing

  • Moved from Postman to REST Assured for integration testing

Full Changelog: v4.5.0...v5.0.0

AAA Server v4.5.0

31 Mar 10:24
124b88b
Compare
Choose a tag to compare

New Features

  • Token Service
    • Introduced new context object to pass arbitrary parameters to APDs
  • Incorporated OpenSSF Best Practices Badge Program

Enhancement

  • Miscellaneous library upgrades and bug fixes

Testing

  • Improved Unit, Integration, Performance and Security testing
  • Enhanced the testing framework with CICD Pipeline for automated testing

AAA Server v4.0.0

30 Sep 11:58
b7319a4
Compare
Choose a tag to compare

New Features

  • Access Policy Domains (APD) service can optionally send back constraints as part of their success response to be encoded into the token issued by the AAA server
  • Enable consumers to withdraw pending access requests for resource access
  • Multiple administrator support
  • Supports users to obtain an identity token for identity verification

Updates, bugs, and performance fixes

  • Enhanced Validation

Test Reports

  • Unit tests available here
  • Coverage available here
  • Security tests available here
  • Integration tests available here

AAA Server v3.5.0

31 Mar 10:41
a1c70e8
Compare
Choose a tag to compare

New Features

  • A new IUDX specific role has been introduced which is responsible for performing any administrative tasks related to the APD (referred to as Data Trustee).
  • New APIs
    • New Authorisation server APIs for Create, List, Update and Delete of APD by a Data Trustee
    • New Access Policy Domain (APD) Server APIs to read and verify User Class
    • Enhanced AAA server Policy flows for APD server integration for Create, Verify policy

Updates, bugs, and performance fixes

  • Enhanced Validation

Test Reports

  • Unit tests available here
  • Coverage available here
  • Security tests available here
  • Integration tests available here

What's Changed

New Contributors

Read more

AAA Server v3.0.0

30 Sep 13:35
d9957cb
Compare
Choose a tag to compare

New Features

  • Adoption of OpenID Connect authentication for all users
  • Discontinuation of the X.509 certificate authentication
  • Move from custom token format to JWT
  • Added consent notifications for consumers to request access to resources from providers
  • Unified delegation roles
  • Server admin policies for providers and delegates
  • Provision for policy constraints
  • Auditing Service
    • Integrated with immutable database (ImmuDB)
  • Migration to Eclipse Vert.x from NodeJS

Updates, bugs, and performance fixes

  • Policies are written only when it refers to existing resources in the Catalogue server
  • Format cleanups of Various API
  • Enhanced Validation
  • Fully complied with IS 18003 (Part 2):2021 Doc No: LITD 28 (17249) | Unified Data Exchange Part 2: API specifications

Test Reports

  • Stress and Endurance Test Report is available here
  • Load and Performance Test Report is available here
  • Unit Test Report is available here
  • Integration Test Report is available here
  • Penetration Test Report is available here