Bearer Authentication ng Okta API

I-authenticate ang programmatic access sa Halo API gamit ang OAuth 2.0 Bearer tokens na inisyu ng Okta.

Pangkalahatang-ideya​

Naglalantad ang Halo ng REST API sa pamamagitan ng serbisyo ng API-Access. Lahat ng API request ay dapat magsama ng valid na Bearer token sa Authorization header. Nakukuha ang mga token mula sa Okta gamit ang OAuth 2.0 Client Credentials flow (machine-to-machine).

Ipinapaliwanag ng gabay na ito kung paano i-configure ang Okta bilang Identity Provider para sa serbisyo ng Halo API-Access, at pagkatapos ay subukan ang integration gamit ang Bearer token authentication.

Mga Kinakailangan​

• Isang tumatakbong deployment ng Halo na may naka-configure na serbisyo ng API-Access
• Isang Okta organization na may admin access
• Okta authorization server na naka-configure para sa Halo (tingnan ang Okta Authorization Server)
• Access sa network mula sa API client papunta sa parehong Okta at sa Halo API endpoint

Pag-setup​

Magrehistro ng API client sa Okta​

Gumawa ng machine-to-machine application​

1. Mag-login sa Okta Admin Console.
2. Pumunta sa Applications -> Applications -> Create App Integration -> API Services.

3. Magbigay ng angkop na pangalan ng App integration: hal. Glasswall Halo API

I-disable ang DPoP (proof of possession)​

4. Pumunta sa tab na General ng application -> seksyong General Settings -> i-click ang Edit.
5. Sa ilalim ng Proof of possession, alisin ang check sa Require Demonstrating Proof of Possession (DPoP) header in token requests.
6. I-save.

Tandaan: Naka-enable ang DPoP sa Okta bilang default para sa mga application ng API Services. Itinatali ng DPoP ang mga token sa cryptographic key ng client, na pumipigil sa mga token replay attack. Gayunpaman, hindi pa kasalukuyang sumusuporta ang serbisyo ng Halo API-Access sa DPoP token validation, kaya dapat itong i-disable para gumana ang Bearer token authentication.

I-configure ang client credentials​

7. Itala ang Client ID at bumuo ng Client Secret.

   export CLIENT_ID="<your-client-id>"
   export CLIENT_SECRET="<your-client-secret>"
   

Tala sa Seguridad: Itago nang ligtas ang mga client secret gamit ang isang secrets manager (hal., Azure KeyVault). Huwag kailanman i-commit ang mga secret sa source control.

I-configure ang mga role (opsyonal)​

8. Kung kailangan ng iyong API client ng write access sa mga endpoint ng license management, tiyaking naka-configure ang role claim sa authorization server na may Admin value na naka-map sa iyong client (tingnan ang API Roles).

Tandaan: Kung wala ang role claim, ang API ay magde-default sa User role. Tingnan ang API Roles to Action Mapping para sa mga detalye kung ano ang maaaring ma-access ng bawat role.

Itala ang issuer URI at audience​

9. Mula sa authorization server na naka-configure sa prerequisite na hakbang:

   export OKTA_ISSUER_URI="https://<your-okta-domain>/oauth2/<authorization-server-id>"
   export VALID_AUDIENCE="api://halo"
   

Magdagdag ng access policy para sa API client​

10. Pumunta sa tab na Access Policies ng authorization server (Security -> API -> piliin ang iyong authorization server -> Access Policies).
11. Add a new access policy:
    • Pangalan: hal. API Client Access
    • Paglalarawan: hal. Access policy for Halo API clients
    • I-assign sa: ang API Services client na ginawa sa itaas (hanapin ayon sa application name na glasswall-halo-api mula sa hakbang 2)
12. Add a rule:
    • Pangalan: hal. Allow API Clients
    • Grant type: Client Credentials
    • Iwan ang ibang mga setting sa mga default o i-adjust ang token lifetime kung kinakailangan.

Tandaan: Ang mga access policy para sa Client Credentials grant ang kumokontrol kung aling mga client (ayon sa client_id) ang maaaring humiling ng mga token. Hindi naaangkop ang group membership dahil walang user context sa flow na ito. I-secure ang access sa API sa pamamagitan ng paghihigpit kung sino ang may client_id at client_secret gamit ang iyong secrets manager.

I-configure ang API-Access service para sa Okta​

Ang cdrplatform-api-access Helm chart ay dapat i-configure upang i-validate ang mga Bearer token na inisyu ng iyong Okta authorization server. Inilalantad ng chart ang mga setting ng authentication sa ilalim ng configuration values key.

I-deploy ang configuration​

Tandaan: Ang Authority at ValidIssuer ay parehong dapat itakda sa Okta issuer URI. Ginagamit ng API-Access service ang Authority upang matuklasan ang JWKS (JSON Web Key Set) para sa pag-validate ng lagda ng token, at ang ValidIssuer upang i-verify ang iss claim sa token.

export HALO_DOMAIN=<your-halo-domain>
helm upgrade --install cdrplatform-api-access cdrplatform-api-access --reuse-values \
  --set configuration.AuthenticationScheme="Bearer" \
  --set configuration.Authentication__Schemes__Bearer__Authority="${OKTA_ISSUER_URI:?}" \
  --set configuration.Authentication__Schemes__Bearer__ValidIssuer="${OKTA_ISSUER_URI:?}" \
  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__0="${VALID_AUDIENCE:?}" \
  --set strategy.type="Recreate" \
  --set ingress.enabled=true \
  --set ingress.tls.enabled=true \
  --set ingress.tls.domain="${HALO_DOMAIN:?}" \
  --atomic

Maramihang audience (opsyonal)​

Kung maraming API client o application ang kailangang mag-access sa Halo API gamit ang magkakaibang audience, magdagdag ng karagdagang mga entry ng ValidAudiences:

  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__0="api://halo-api" \
  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__1="<second-client-id>" \
  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__2="<third-client-id>"

Paggamit ng Halo API​

Kumuha ng bearer token​

Daloy ng Client Credentials (machine-to-machine)​

Gamitin ang daloy na ito para sa mga automated system, CI/CD pipeline, at service-to-service integration kung saan walang kinakailangang interaksiyon ng user.

export TOKEN_ENDPOINT="${OKTA_ISSUER_URI}/v1/token"

Humiling ng token:

curl -s -X POST "${TOKEN_ENDPOINT}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "scope=halo.api"

Halimbawang tugon:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "halo.api"
}

I-extract ang token:

export ACCESS_TOKEN=$(curl -s -X POST "${TOKEN_ENDPOINT}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "scope=halo.api" | jq -r '.access_token')

I-authenticate ang mga API request​

Isama ang Bearer token sa Authorization header ng bawat API request:

export HALO_API_URL="https://<your-halo-domain>"

I-verify ang authentication​

Subukan gamit ang isang protected endpoint. Ang request na walang token ay dapat magbalik ng 401, at ang request na may valid token ay dapat magbalik ng 200:

# Without token - expect 401
curl -s -o /dev/null -w "%{http_code}" \
  "${HALO_API_URL}/api/v1/policies"

# With token - expect 200
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  "${HALO_API_URL}/api/v1/policies"

Halimbawa: Magsumite ng file para sa pagproseso​

curl -s -X POST \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -F "file=@/path/to/document.pdf" \
  "${HALO_API_URL}/api/v1/rebuild/file" \
  --output rebuilt_document.pdf

Pag-troubleshoot​