Authentication Mutations

GraphQL mutations for authenticating with the Satélite API

authenticate

Authenticates a user using a Microsoft Azure AD JWT token and returns a Satélite session with user details, permissions, and a new session token.

Mutation Signature

mutation {
  authenticate: SessionDTO!
}

This mutation is marked with [AllowAnonymous] and does not require a Satélite session token. However, it requires a valid Azure AD JWT token in the Authorization header.

Headers

Authorization · string · required

Microsoft Azure AD JWT token in the format: Bearer <AZURE_AD_TOKEN>

The token must contain:

• unique_name or upn claim with email ending in @moderna.com.ec
• name claim with the user’s full name

Response

Returns a SessionDTO object containing:

token · string · required

JWT session token for subsequent API requests. Valid for 120 minutes.

This token contains:

• sub - User ID
• email - User email
• rol - User role ID
• scopes - User permissions array

usuario · UsuarioDTO · required

Authenticated user information

Show UsuarioDTO properties

id · int

Unique user identifier

nombre · string

User’s full name

email · string

User’s email address

activo · boolean

Whether the user account is active

idRol · int?

User’s role ID (nullable)

idPlanta · int?

User’s assigned plant ID (nullable)

rol · RolesDTO?

User’s role details (nullable)

createdAt · DateTime?

Timestamp of user creation

updatedAt · DateTime?

Timestamp of last user update

permisos · UsuarioPermisosDTO[] · required

List of permissions assigned to the user

Show UsuarioPermisosDTO properties

id · int

Permission assignment ID

idUsuario · int

User ID

idPermiso · int

Permission ID

acciones · string?

Allowed actions for this permission (nullable)

permiso · PermisoDTO?

Detailed permission information (nullable)

menu · MenuDTO[] · required

Dynamically generated menu items based on user permissions

Show MenuDTO properties

id · int

Menu item ID

label · string

Display label for the menu item

url · string

URL path for the menu item

idPadre · int?

Parent menu item ID for nested menus (nullable)

idPermiso · int?

Associated permission ID (nullable)

orden · int

Display order for the menu item

nivel · int

Nesting level of the menu item

Example Request

mutation AuthenticateUser {
  authenticate {
    token
    usuario {
      id
      nombre
      email
      activo
      idRol
      rol {
        id
        nombre
      }
    }
    permisos {
      id
      idPermiso
      acciones
      permiso {
        id
        nombre
      }
    }
    menu {
      id
      label
      url
      idPadre
      orden
      nivel
    }
  }
}

Example Response

{
  "data": {
    "authenticate": {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjMiLCJlbWFpbCI6Impkb2VAbW9kZXJuYS5jb20uZWMiLCJyb2wiOiI1Iiwic2NvcGVzIjpbInVzZXI6aW1wZXJzb25hdGUiXSwiZXhwIjoxNzA5NTg3MjAwfQ.xyz",
      "usuario": {
        "id": 123,
        "nombre": "John Doe",
        "email": "[e-mail]",
        "activo": true,
        "idRol": 5,
        "rol": {
          "id": 5,
          "nombre": "Administrador"
        }
      },
      "permisos": [
        {
          "id": 1,
          "idPermiso": 10,
          "acciones": "read,write,delete",
          "permiso": {
            "id": 10,
            "nombre": "Vista Usuario"
          }
        },
        {
          "id": 2,
          "idPermiso": 15,
          "acciones": "read,write",
          "permiso": {
            "id": 15,
            "nombre": "Gestión Proyectos"
          }
        }
      ],
      "menu": [
        {
          "id": 1,
          "label": "Dashboard",
          "url": "/dashboard",
          "idPadre": null,
          "orden": 1,
          "nivel": 1
        },
        {
          "id": 2,
          "label": "Usuarios",
          "url": "/usuarios",
          "idPadre": null,
          "orden": 2,
          "nivel": 1
        },
        {
          "id": 3,
          "label": "Ver Usuarios",
          "url": "/usuarios/lista",
          "idPadre": 2,
          "orden": 1,
          "nivel": 2
        }
      ]
    }
  }
}

Response Headers

The API also returns the session token in the response headers:

satelite_session: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

You can use either the token field from the response body or the satelite_session header value for subsequent API requests.

Error Responses

Invalid or Missing Token

{
  "errors": [
    {
      "message": "Sessión no válida",
      "extensions": {
        "code": "UNAUTHORIZED"
      }
    }
  ]
}

Error Codes

UNAUTHORIZED · error

Returned when:

• Azure AD token is missing or invalid
• Email domain is not @moderna.com.ec
• User account is inactive (activo = false)
• User has no permissions assigned

Action: Verify your Azure AD token, check account status, or contact an administrator to assign permissions.

Authentication Flow

1. Obtain Azure AD Token

   Authenticate with Microsoft Azure AD using your organization credentials to obtain a JWT token.

2. Call authenticate Mutation

   Send a GraphQL mutation request to authenticate with the Azure AD token in the Authorization header.

3. Receive Session Token

   Store the returned token from the SessionDTO response securely.

4. Use Session Token

   Include the session token in the Authorization header for all subsequent API requests:

   Authorization: Bearer <SATELITE_SESSION_TOKEN>
   
5. Handle Token Expiration

   When the token expires (after 120 minutes), re-authenticate using the same process.

Implementation Notes

Token Validation

The authentication process validates the Azure AD token by:

1. Extracting the token from the Authorization header (removing “Bearer ” prefix)
2. Reading JWT claims using JwtSecurityTokenHandler
3. Looking for email in unique_name or upn claims
4. Verifying the email ends with @moderna.com.ec
5. Extracting the user’s name from the name claim

User Creation

New users are automatically created when they authenticate for the first time. The system:

1. Checks if a user with the email exists in the database
2. If not found, creates a new user with:
   • Email from the Azure AD token
   • Name from the Azure AD token
   • Active status set to true
   • Current timestamp as CreatedAt

Permission Loading

The system loads:

1. User permissions from the Usuarios_Permisos table
2. Associated menu items for each permission
3. Permission details including names and IDs

Token Generation

The Satélite session token is generated with:

• Algorithm: HMAC SHA-256
• Expiration: 120 minutes from generation
• Claims: User ID, email, role ID, and scopes
• Scopes: Dynamically assigned based on permissions (e.g., users with “Vista Usuario” permission receive user:impersonate scope)

Source Code Reference

For implementation details, refer to:

• Schema/Authentication/Mutation/AuthenticationMutation.cs:14 - Mutation definition
• Services/Authentication/AuthenticationRepository.cs:28 - Authentication logic
• Services/Authentication/AuthenticationRepository.cs:106 - Token generation