Configuration

AuthenticationType.LOCAL

Authentication Types

To select a 'type' inside the security configuration you need to enter any of these options as using just strings is deprecated:

• AuthenticationType.LOCAL
• AuthenticationType.LDAP
• AuthenticationType.OIDC
• AuthenticationType.DELEGATED

Example Configuration

CONFIG = {
    # *******************************************************************************
    'security': {
        'authentication': {
            'enabled': False,
            'type': AuthenticationType.OIDC,
            'secret': os.getenv('AUTH_SECRET', default='52ecfd60e01b800355a8ce59780f9243b4662c3a236394ee'),
            'force_https_original_url_redirection': False,

            'anonymous': {
                'id': 'Anonymous',
                'account': '[email protected]',
                'name': 'Anonymous',
                'displayName': 'Anonymous'
            },

            'local': {
                ...
            },

            'delegated': {
                ...
            },

            'ldap': {
                ...
            },

            'oidc': {
                ...
            }
         }
    }     
}

Attributes Mapping 

Almost every method available in GAIA-API has a property called attributesMapping, this property is used to remap any value in the user data provided by the authentication service into the User data available throughout the server. This transformation is achieved by mapping each key:value pair, where the value is looked up as a key in the user data from the service and remapped with the key in the User data for the server. The original key is kept, as well as any other unspecified values.

Cookie Configuration 

Methods

Local 

This authentication method uses a CSV file, which involves storing user credentials in a structured format for authentication purposes. In this case, we have a CSV file with the following headers: id, account, password, email, roles, and disabled.

• ID: Unique ID for the user
• Account: User credential necessary for the login
• Password: User password
• Email: User Email 
• Roles: List of different role names assigned to each user
• Disabled: Boolean indicating whether the user account is disabled

Configuration

Example Configuration

'local': {
 	'file': '/path/to/user.csv'
}

Example CSV File

id,account,password,email,roles,disabled
1,user1,pass123,[email protected],"role1, role2",false
2,user2,pass456,[email protected],"role2, role3",true

LDAP 

LDAP (Lightweight Directory Access Protocol) is a widely adopted protocol for accessing and managing directory information services. It is a lightweight, platform-independent, and network-oriented protocol designed for directory services such as user authentication, authorization, and directory information retrieval.

LDAP is based on a client-server model, where a client application interacts with an LDAP server to perform various directory operations. The LDAP server acts as a centralized repository that stores and manages directory entries, which typically represent users, groups, devices, or other resources within an organization.

Configuration

Example Configuration

'ldap': {
  "url": os.getenv('LDAP_URL', default="ldap://ldap.example.com"),
  "authentication": "SIMPLE",
  "bindDN": "cn=admin,dc=example,dc=com",
  "bindCredentials": os.getenv('LDAP_CREDENTIALS'),
  "searchBase": "ou=users,dc=example,dc=com",
  "searchFilter": "(objectClass=person)",
  "searchAttributes": ["cn", "email"],
  "tlsOptions": {
    "certificateVerification": true,
    "cipherSuites": ["TLS_RSA_WITH_AES_256_CBC_SHA256"],
    "clientCertificate": "/path/to/client_certificate.pem",
    "clientKey": "/path/to/client_key.pem"
  },
  "bindProperty": "uid",
  "groupDnProperty": "memberOf",
  "groupSearchBase": "ou=groups,dc=example,dc=com",
  "groupSearchFilter": "(objectClass=group)",
  "attributesMapping": {
    "id": "uid",
    "account": "sAMAccountName",
    "roles": "client_roles"
   }
}

SAML 

SAML2 (Security Assertion Markup Language 2.0) authentication is a standard protocol used for exchanging authentication and authorization data between a Service Provider (SP) and an Identity Provider (IdP). It enables secure single sign-on (SSO) functionality, allowing users to authenticate once with the IdP and access multiple services provided by different SPs without the need to re-enter credentials.

Configuration

SAML Security Configuration

Example Configuration

'saml': {
  "strict": False,
  "debug": False,
  "json_redirect": False,
  "entity_id": "https://your-idp.com/entity",
  "single_sign_on_service_url": "https://your-idp.com/sso",
  "single_sign_on_service_binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "single_logout_service_url": "https://your-idp.com/slo",
  "single_logout_service_binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
  "callback_url": "http://your-app.com/auth/saml/callback",
  "x509cert_path": "/path/to/certificate.pem",
  "x509cert": "-----BEGIN CERTIFICATE-----\n...certificate content...\n-----END CERTIFICATE-----",
  "cert_fingerprint": "AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01",
  "cert_fingerprint_algorithm": "sha256",
  "security": {
    "nameIdEncrypted": False,
    "authnRequestsSigned": False,
    "logoutRequestSigned": False,
    "logoutResponseSigned": False,
    "signMetadata": False,
    "wantMessagesSigned": False,
    "wantAssertionsSigned": False,
    "wantAssertionsEncrypted": False,
    "wantNameId": True,
    "wantNameIdEncrypted": False,
    "wantAttributeStatement": True,
    "requestedAuthnContext": True,
    "requestedAuthnContextComparison": "exact",
    "failOnAuthnContextMismatch": False,
    "metadataValidUntil": "2023-12-31T23:59:59Z",
    "metadataCacheDuration": "PT24H",
    "allowSingleLabelDomains": False,
    "signatureAlgorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
    "digestAlgorithm": "http://www.w3.org/2001/04/xmlenc#sha256",
    "allowRepeatAttributeName": False,
    "rejectDeprecatedAlgorithm": True
  },
  "cookie": {
    "max_age": 12,
    "expires": 12,
    "path": "/es",
    "domain": os.getenv("COOKIE_DOMAIN_NAME"),
    "secure": False,
    "httponly": False,
    "samesite": "lax"
  },
  "attributesMapping": {
    "id": "userID",
    "account": "email",
    "roles": "client_roles"
   }
}

OIDC 

OIDC (OpenID Connect) authentication is an authentication protocol built on top of the OAuth 2.0 framework. It provides a standardized way for clients (relying parties) to authenticate users by leveraging an Identity Provider (IdP).Configuration

Configuration

Example Configuration

'oidc': {
  "client_id": os.getenv('OIDC_CLIENT_ID'),
  "openid_configuration_uri": os.getenv('OIDC_OPENID_CONFIG_URI'),
  "callback_url": "http://localhost:8085/es/auth/oidc/callback",
  "disable_jwt_verification": False, 
  "json_redirect": False,
  "scope": ["openid", "email", "profile"],
  "cookie": {
    "max_age": 12,
    "expires": 12,
    "path": "/es",
    "domain": os.getenv("COOKIE_DOMAIN_NAME"),
    "secure": False,
    "httponly": False,
    "samesite": "lax"
  },
  "attributesMapping": {
    "id": "sub",
    "account": "email",
    "roles": "client_roles"
   }
}

Delegated (JWKS) 

Delegated is a JWT validation with JWKS (JSON Web Key Set) involves verifying the authenticity and integrity of a JWT by using public keys obtained from the IdP's JWKS endpoint.By utilizing JWKS for JWT validation, the client can ensure that the token was issued by a trusted party (IdP) and has not been tampered with. The use of public keys enables cryptographic verification, as only the corresponding private key held by the IdP can produce a valid signature for the JWT.

Configuration

Example Configuration

'delegated': {
  "debug": False,
  "jwks_url": os.getenv('DELEGATE_JWKS_URL'),
  "audience": "your-service-audience",
  "attributesMapping": {
    "id": "sub",
    "account": "email",
    "roles": "client_roles"
  }
}

'delegated': {
	'jwks_url': f"https://login.microsoftonline.com/{os.getenv('TENANT')}/discovery/v2.0/keys",
	'audience': os.getenv('AUDIENCE'), #ClientID
	'attributesMapping': {
		# key is the property name stored in the SEIA user profile,
		# the value is the user attribute in LDAP

		'id': 'appid',  # _id is required
		'account': 'appid'  # account is for roles and group expansion
	}

}

Encryption

The Encryption section of the SearchAPI project documentation provides an overview of the encryption functionalities implemented within the project. Encryption is a vital aspect of securing sensitive data, ensuring its confidentiality and integrity.

This section focuses on two essential functions: encrypt and decrypt. These functions are part of the utils.crypto module and provide convenient encryption and decryption capabilities for developers working on the SearchAPI project.

Configuration

Example Configuration

This section provides an overview of the encryption mechanisms used in the SearchAPI project to secure sensitive data during transit and at rest. 

'encryption': {
  "secret_key": "/path/to/secret.key"
}

or

'encryption': {
  "secret_key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

Inner Crypto Module (utils.crypto)

The utils.crypto module provides various encryption and cryptographic utility functions used within the SearchAPI project. These functions are designed to ensure the security and integrity of sensitive data. This document outlines the available functions and their usage.

Hashing Functions

hash_sha256

This function computes the SHA-256 hash of the input data and returns it as a hexadecimal code. The data parameter can be either a string or a byte array. The returned hash value is a string.

hash_sha1

This function computes the SHA-1 hash of the input data and returns it as a hexadecimal code. The data parameter can be either a string or a byte array. The returned hash value is a string.

Generating Keys and Initialization Vectors (IV)

generate_iv

This function generates a random Initialization Vector (IV) of 16 bytes. The IV is used for encryption and decryption processes and ensures the uniqueness and unpredictability of encrypted data.

generate_secret_key

This function generates a secret key of the specified size (default is 32 bytes). The secret key is used for encryption and decryption. The returned key is a base64-encoded string.

Encryption and Decryption

is_encrypted

This function checks whether the given text is encrypted. It returns True if the text has the expected encryption prefix ("encrypted:").

encrypt

This function encrypts the provided text using AES encryption. If an initialization vector (iv) is not provided, a random IV is generated. The encrypted text is returned with the prefix "encrypted:" and includes the IV and ciphertext.

decrypt

This function decrypts the given text using AES decryption. If the text is not encrypted (does not have the encryption prefix), it returns the original text. Otherwise, it extracts the IV and ciphertext from the encrypted text and performs decryption to obtain the original plaintext.

Usage

To use the functions from utils.crypto, you can import them as follows:

from utils.crypto import hash_sha256, hash_sha1, generate_iv, generate_secret_key, is_encrypted, encrypt, decrypt

You can then call the functions according to your requirements. For example:

data = "Hello, World!"

# Compute SHA256 hash
hash_value = hash_sha256(data)
print(f"SHA256 hash: {hash_value}")

# Generate a random IV
iv = generate_iv()
print(f"Generated IV: {iv}")

# Generate a secret key
secret_key = generate_secret_key()
print(f"Generated secret key: {secret_key}")

# Check if a text is encrypted
encrypted_text = encrypt(data)
is_text_encrypted = is_encrypted(encrypted_text)
print(f"Is the text encrypted? {is_text_encrypted}")

# Decrypt the encrypted text
decrypted_text = decrypt(encrypted_text)
print(f"Decrypted text: {decrypted_text}")

Accesing User Information

The user information is available in all the request, at any point of the code after the Security check, to access this information you can put req.state.user

from starlette.requests import Request
from typing import List
from gaia_core.models.security import User
 
router = APIRouter(prefix=f'/{os.path.basename(__file__)[:-3]}')


@router.get("/route")
async def route_handler(req: Request):

	# Get the user Roles
	user:User = req.state.user

Roles

This configuration allows to add additional role for role verification using a CSV file. The file should contain the following headers:

• ID: Unique ID for the role
• Role: Display name of the role
• Value: Numeric value assigned to the role for hierarchical comparisons

These roles are later loaded into the RoleManager, which by default has five roles defined: UNAUTHORIZED, ANONYMOUS, USER, ADMIN, READ_ONLY.

Configuration

Example Configuration

'roles': {
    'file': '/path/to/roles.csv'
    'role_equivalents_map': {
    	'unauthorized': 'no_auth',
        # 'anonymous':
        'user': 'write',
        'admin': ['super_user', 'administrator'],
        'read_only': ['read'],
        'root': ['adminIT']
    }
}   

Explanation for role equivalent:

The code checks if there are role equivalents defined in the configuration and processes each key-value pair, where the keys are primary roles and the values are either single or multiple equivalent roles. For each equivalent role, it uses the get_or_create method to ensure the role exists, assigning it the same name and value as the original role but with a different ID. This guarantees that all roles and their equivalents specified in the configuration are created and managed in the system, maintaining consistent attributes except for the unique ID.

Example Role CSV

ID,Role,Value
1,Admin,100
2,User,50
3,Guest,10

Roles Generated from Attribute Mapping 

For the roles mapped in the attributesMapping field from any of the authentication methods above, these are generated into the Roles Manager, using the name of the role as the ID, meaning you would be able to use this roles as any other default role, by using:

custom_role = roles_manager.get('Support')

Accessing the Roles of the User

To access the user roles, you first need to include the request in the endpoint, after that just access the state, then the user and finally the roles. We recomend to store the roles in a variable of type List[Role]

from starlette.requests import Request
from typing import List
from models.security import Role
outer = APIRouter(prefix=f'/{os.path.basename(__file__)[:-3]}')
@router.get("/route")
async def route_handler(req: Request):

# Get the user Roles
roles: List[Role] = req.state.user.roles

Role Manager 

The RolesManager class is responsible for managing roles within the SearchAPI project. It allows the creation, retrieval, and modification of roles.

Usage

To use the RolesManager, you can import anywhere in the code as follows:

from models.security import roles_manager

Creating Roles

The RolesManager class provides the get_or_create method to create and retrieve roles. You can create a new role or get an existing one using the get_or_create method.

# Create or get the "user" role
user_role = roles_manager.get_or_create(id="user", name="User", value=10)

# Create or get the "admin" role
admin_role = roles_manager.get_or_create(id="admin", name="Admin", value=100)

If a role with the specified id already exists, it will be retrieved. Otherwise, a new role will be created.

Retrieving Roles

To retrieve a role by its id, you can use the get_role method:

# Get the "user" role
user_role = roles_manager.get_role("user")

# Get the "admin" role
admin_role = roles_manager.get_role("admin")

If the specified role does not exist, a new role with the provided id will be created and returned.

Modifying Roles

The RolesManager class allows you to overwrite the properties of an existing role using the overwrite_role method:

# Create a new role
custom_role = Role(id="custom", name="Custom Role", value="custom_value")

# Overwrite the "user" role with the custom role
roles_manager.overwrite_role(custom_role)

or

# Create or get the "user" role
user_role = roles_manager.get_role("user")

# Overwrite the "user" role with the new values
admin_role = roles_manager.get_or_create(id="user", name="User", value=50, overwrite=True)

Predefined Roles

The RolesManager class also defines several predefined roles as class attributes:

• UNAUTHORIZED: Represents an unauthorized role.
• ANONYMOUS: Represents an anonymous role.
• USER: Represents a user role.
• ADMIN: Represents an admin role.
• READ_ONLY: Represents a read-only role.
• ROOT: Represents a role above application admins, like IT admins

These roles can be accessed directly from the RolesManager instance:

# Access the predefined roles
unauthorized_role = roles_manager.UNAUTHORIZED
anonymous_role = roles_manager.ANONYMOUS
user_role = roles_manager.USER
admin_role = roles_manager.ADMIN
read_only_role = roles_manager.READ_ONLY
root = roles_manager.ROOT

By utilizing the RolesManager class, you can easily create, retrieve, and modify roles within the SearchAPI project.

Role API Verification

The RoleVerifications class is a dependency class designed for FastAPI. It provides role-based authorization checks for user requests. This documentation describes the available methods and their usage.

Usage

To use the RoleVerifications class, you can create an instance of it with the desired roles:

role_verifications = RoleVerifications(roles=[roles_manager.ADMIN, roles_manager.READ_ONLY, roles_manager.get('Support')])

or

# Declared directly in the route with the verification type
@router.get('/route', dependencies=[RoleVerifications([roles_manager.ADMIN, roles_manager.READ_ONLY, roles_manager.get('Support')]).requires_all()])

requires_any

The requires_any method allows access to users with any of the defined roles. 

@router.get("/route", dependencies=[RoleVerifications([roles_manager.ADMIN, roles_manager.get('Support')]).requires_any()])
async def route_handler():     # Handle route logic

requires_all

The requires_all method allows access to users who have all of the defined roles. 

@router.get("/route", dependencies=[RoleVerifications([roles_manager.ADMIN, roles_manager.get('Support')]).requires_all()])
async def route_handler():
    # Handle route logic

forbid_any

The forbid_any method forbids access to users with any of the defined roles.

@router.get("/route", dependencies=[RoleVerifications([roles_manager.ADMIN, roles_manager.get('Support')]).forbid_any()])
async def route_handler():
     # Handle route logic

forbid_all

The forbid_all method forbids access to users who have all of the defined roles.

app.get("/route", dependencies=[RoleVerifications([roles_manager.ADMIN, roles_manager.get('Support')]).forbid_all()])
async def route_handler():
     # Handle route logic

higher_than

The higher_than method forbids access to users who have a role value lower or equals to the ones specified

@router.get("/route", dependencies=[RoleVerifications([roles_manager.ADMIN, roles_manager.get('Support')]).higher_than()])
async def route_handler():
     # Handle route logic

higher_equals

The higher_equals method forbids access to users who have  a role value lower to the ones specified

@router.get("/route", dependencies=[RoleVerifications([roles_manager.ADMIN, roles_manager.get('Support')]).higher_equals()])
async def route_handler():
     # Handle route logic

equals

The equals method forbids access to users who have  a role value different to the ones specified

@router.get("/route", dependencies=[RoleVerifications([roles_manager.ADMIN, roles_manager.get('Support')]).equals()])
async def route_handler():
     # Handle route logic

By utilizing the methods provided by the role verification, you can enforce role-based authorization checks in your FastAPI routes, ensuring that only users with the required roles can access the protected endpoints.

Headers

This configuration allows to add additional headers on GAIA API's responses. 

Configuration

Example Configuration

'headers': {
    'include': [
        ('strict-transport-security', 'max-age=31536000;includeSubDomains')
    ]
}