Authentication

You will need to authenticate your application using OAuth2 protocol. Depending on which API you want to use authorization method may differ :

• user login : Bouygues Telecom login with Oauth2 authorization code flow to get an access token
• app credentials : using the consumer id and consumer secret to get an access token
• app credentials with certificate : using a signed JWT certificate

User login

For API requiring end user authentication, user will login to your application using Bouygues Telecom authentication. After successfull login, the user will be redirected to the URL you've specified as callback URL when you've created your app on the developer portal.

In order to get an access token, you need to implement Oauth2 authorization code flow

The flow is the following :

Authorize URL

call the authorize URL including the client_id, redirect_uri, response_type url parameter like the following :

GET https://oauth2.bouyguestelecom.fr/authorize?client_id=testing.bouyguestelecom.fr&response_type=code&redirect_uri=https://partner.callback.acme/callback

• client_id value can be found in the app details on your developer account
• response_type has always the value code
• redirect_uri is the callback URL you've referenced in your app on your developer account

Live example: https://oauth2.sandbox.bouyguestelecom.fr/ap4/authorize?client_id=apim.consodata.testing.bouyguestelecom.fr&response_type=code&redirect_uri=https://bbox.ai/auth/callback

User login

User logs in using Bouygues Telecom credentials (official Bouygues Telecom account)

Redirection to your backend

Upon successfull login, user gets redirected to your callback URL, you will receive a code in url parameter like this :

GET https://partner.callback.acme/callback?code=ac-95223380-749d-49eb-ac06-594bf7ef8ff0

Get an access token

Extract this code url parameter and exchange it for an access token using the token endpoint :

POST https://oauth2.bouyguestelecom.fr/token?grant_type=authorization_code&code=ac-95223380-749d-49eb-ac06-594bf7ef8ff0

You will need to pass a redirect_uri parameter in the body in form-url-encoded format.

You also need an Authorization http header for Basic authentication using the consumer id / consumer secret that were generated when you've created your app on Bouygues developer account. The Authorization http header has a value in the following format :

Authorization: Basic base64([consumer id]:[consumer secret])

Note that the request body is form url encoded and response body is json encoded

curl example :

curl "https://oauth2.bouyguestelecom.fr/token" \
    -H "Authorization: Basic $(echo -n 'testing.bouyguestelecom.fr:your.consumer.secret' | base64 -w 0)" \
    -d "grant_type=authorization_code" \
    -d "code=ac-95223380-749d-49eb-ac06-594bf7ef8ff0" \
    --data-urlencode "redirect_uri=https://partner.callback.acme/callback"

Output example :

{
  "access_token": "at-e211bd32-80f1-4945-956f-bb7a8782e37a",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_credit": 0,
  "scope": "ConsommationConsult openid identifiers roles profile",
  "id_token": "eyJraWQ....kAYQ"
}

User info

To get access to bougues telecom infos, you can use the POST UserInfo route.

For example on AP4:

https://oauth2.sandbox.bouyguestelecom.fr/ap4/userinfo

It will return a payload like

{
    "sub": "3c268bb85512121d15b89057ad1704dcd370cd232c2966dbf9e7f43cae8a91af",
    "login_type": "COMPTE_WEB_PROSPECT",
    "roles": [
      "CLIENT_SP"
    ],
    "given_name": "TOPSI",
    "acr": "urn:bouyguestelecom:acr:classes:low",
    "user_type": "CLIENT",
    "name": "Topsi Testtopsiun",
    "target_identity": false,
    "partnerId": "8fc95d1f-8f5d-42c8-bd01-6c624c8d2179",
    "family_name": "TESTTOPSIUN"
}

The following informations may be the most usefull:

• given_name
• family_name

App credentials

This flow uses client credentials Oauth2 flow. It consists in calling the token endpoint to get an access token using your consumer key / consumer secret

The flow is the following :

Get an access token

make a call to POST https://oauth2.bouyguestelecom.fr/token like the following :

POST https://oauth2.bouyguestelecom.fr/token
grant_type=client_credentials

You also need an Authorization http header for Basic authentication using the consumer id / consumer secret that were generated when you've created your app on Bouygues developer account. The Authorization http header has a value in the following format :

Authorization: Basic base64([consumer id]:[consumer secret])

Note that the request body is form url encoded and response body is json encoded

curl example :

curl "https://oauth2.bouyguestelecom.fr/token" \
    -H "Authorization: Basic $(echo -n 'testing.bouyguestelecom.fr:your.consumer.secret' | base64 -w 0)" \
    -d "grant_type=client_credentials"

Output example :

{
  "access_token": "at-9ebf70bd-1cc6-412d-b1ba-3997f8dcad19",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_credit": 0,
  "scope": "PersonneConsult"
}

App credentials with certificate

This flow is replacing « App credentials » with the aim of improving security. Like its predecessor it relies on requesting an access token from the Bouygues Telecom’s Authorisation server, leveraging a signed certificate.

The flow works as follows :

Get an access token

make a call to POST https://oauth2.bouyguestelecom.fr/token like the following :

POST https://oauth2.bouyguestelecom.fr/token
grant_type=client_credentials

A notable specificity of this workflow lies in the fact that, unlike "standard client credentials" it doesn't rely on the authorization header. Instead, all parameters are passed in the body of the request (Content-type = application/x-www-formurlencoded).

Here is the detailed body content :

Key	Value	Mandatory	Comment
grant_type	client_credentials	Yes
client_assertion_type	urn:ietf:params:oauth:client-assertion-type:jwt-bearer	Yes
client_assertion		Yes	JWT format, signed with you private key

Details about the assertion JWT header :

Claim	Value	Comment
kid	"apim-provisioner"	Fixed value
alg	"RS256"	Signature algorythme : Fixed value
use	"sig"	Fixed value
typ	"JWT"	Fixed value

Details about the assertion JWT payload :

Claim	Value
iss	your consumer key
sub	your consumer key (again)
aud	Bouygues Telecom Authorization server URL (/token endpoint) see details below
iat	Creation date of this assertion (RFC3339 based timestamp)
exp	Expiration date of this assertion (RFC3339 based timestamp)
jti	Unic ID of this assertion

Here is a valid JWT payload example :

{ 
   "iss": "app-cc-jwt", 
   "sub": "app-cc-jwt", 
   "aud": "https://iam.sandbox.bouyguestelecom.fr/.../token", 
   "iat": 1642690624, 
   "exp": 1642695012, 
   "jti": "123456789"
}   

Note that our authorization server will first validate your assertion signature using the Public Key that you provided.

curl example :

curl --location --request POST 'https://mon-compte.sandbox.bouyguestelecom-entreprises.fr/ap2/realms/entreprise/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
--data-urlencode 'client_assertion={{test_cc_assertion}}’

Output example :

{
    "access_token": "eyJhbGciOiJSUzI1N ... jXVt7AVOWGpkGcm5fIF7Ph8vDeLBuLLYZxdap_PKX12QBoo6tzHYeB3SYxVlx9hSNnEuq0A",
    "expires_in": 300,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "ENT_ContratServicesManage ENT_ContratServicesConsult"
}

List all Oauth Endpoints

By clicking on

• https://oauth2.bouyguestelecom.fr/.well-known/openid-configuration

you can have access to all the oauth endpoints.

You will received a json response

{
    "issuer": "https://oauth2.sandbox.bouyguestelecom.fr/ap4",
    "authorization_endpoint": "https://oauth2.sandbox.bouyguestelecom.fr/ap4/authorize",
    "token_endpoint": "https://oauth2.sandbox.bouyguestelecom.fr/ap4/token",
    "userinfo_endpoint": "https://oauth2.sandbox.bouyguestelecom.fr/ap4/userinfo",
    "revocation_endpoint": "https://oauth2.sandbox.bouyguestelecom.fr/ap4/revoke",
    "jwks_uri": "https://oauth2.sandbox.bouyguestelecom.fr/ap4/jwks.json",
    "end_session_endpoint": "https://www.mon-compte.sandbox.bouyguestelecom.fr/ap4/cas/logout",
    "response_types_supported": [
        "code",
        "id_token",
        "code id_token",
        "token id_token",
        "token"
    ],
    "response_modes_supported": [
        "query",
        "fragment"
    ],
    "subject_types_supported": [
        "public"
    ],
    "id_token_signing_alg_values_supported": [
        "RS256"
    ],
    "scopes_supported": [
        "openid",
        "profile",
        "email",
        "identifiers",
        "roles"
    ],
    "claims_supported": [
        "sub",
        "aud",
        "iss",
        "iat",
        "auth_time",
        "exp",
        "login",
        "name",
        "family_name",
        "given_name",
        "email",
        "user_type",
        "login_type",
        "roles"
    ]
}

"OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 protocol and supported by some OAuth 2.0 providers [...]. OpenID Connect defines a discovery mechanism, called OpenID Connect Discovery, where an OpenID server publishes its metadata at a well-known URL, typically https://server.com/.well-known/openid-configuration"

Source