Package: baikal-sdk
Python 3 SDK for BaikalSDK to easilly generate tokens for an application in the 4th platform. It can be used asynchronously for aiohttp or asyncio frameworks.NOTE: Starting from v0.1.3, the license has changed to Apache 2.0InstallationYou can install easily with pip:pipinstallbaikal-sdkUsageCreate a clientfromclients.baikal_clientimportOpenIDClientoidc_client=OpenIDClient(authserver_endpoint='https://auth.xxx.baikalplatform.com',# authserver endpointclient_id='your_oauth_client_id',client_secret='your_oauth_client_secret',# For using grantUser method (jwt-bearer grant type)client_keys=[{'key':'stringWithTheKey',format:'pem'}],# optionalissuer='http://yourserver.com/',# your jwt issuer idprivate_certs_path='/path/to/certs/directory'# directory to read certificates/private keys.)If you want to use in an asynchronous environment:fromclients.aio.baikal_clientimportOpenIDClientoidc_client=OpenIDClient(authserver_endpoint='https://auth.xxx.baikalplatform.com',# authserver endpointclient_id='your_oauth_client_id',client_secret='your_oauth_client_secret',# For using grantUser method (jwt-bearer grant type)client_keys=[{'key':'stringWithTheKey',format:'pem'}],# optionalissuer='http://yourserver.com/',# your jwt issuer idprivate_certs_path='/path/to/certs/directory'# directory to read certificates/private keys.)the asynchronous client will use aiohttp client to perform requests to authserver and will handle the asynchronous
session internally. Seeaiohttp_example.pyfor a real example.Get an access_token for a user using jwt-beareraccess_token=oidc_client.grant_user('userSUB',['list','of','scopes'],['list','of','purposes'],authorization_id='46921050-e97c-418b-928c-4158256be92c',# optionalidentifier={'id':'my-phone-number','type':'phone_number'},# optionalfull_authserver_response=False# optional (get full response, including expires_in, scopes ...))to use it asynchronously (e.g. with aiohttp):access_token=awaitoidc_client.async_grant_user('userSUB',['list','of','scopes'],['list','of','purposes'],authorization_id='46921050-e97c-418b-928c-4158256be92c',# optionalidentifier={'id':'my-phone-number','type':'phone_number'}# optional)Get a client_credentials access_tokenaccess_token=oidc_client.grant_client(scopes=['list','of','scopes']#optionalpurposes=['list','of','purposes']#optional)The methods can be called asynchronously using await:access_token=awaitoidc_client.async_grant_client(...)Introspect access_tokenpayload=oidc_client.introspect(access_token)assert'scope-sep-string'inpayload['scope']The upper methods can be called in an asynchronous environment using await:access_token=awaitoidc_client.async_introspect(...)Expose your public keys in a server route to use with ajwt-bearerIf you have configured your issuer in the authserver to read from an endpoint,
you should expose your public keys in an accessible route.oid_client.get_jwk_set()This will output the public part of your keys to be directly exposed in JWK format (required by authserver and any OIDC server).ConfigurationTheOpenIDClientconfiguration will be read from environment if ommitedexport BAIKAL_AUTHSERVER_ENDPOINT='https://auth.xxx.baikalplatform.com'
export BAIKAL_CLIENT_ID='your_oauth_client_id'
export BAIKAL_CLIENT_SECRET='your_oauth_client_secret'
export BAIKAL_ISSUER='http://yourserver.com/'
export BAIKAL_PRIVATE_CERTS_PATH='/path/to/certs/directory'Supported certs format are (should match the file extension):json: JSON stringified JWKprivate: DER encoded 'raw' private keypkcs8: DER encoded (unencrypted!) PKCS8 private keypublic: DER encoded SPKI public key (alternate to 'spki')spki: DER encoded SPKI public keypkix: DER encoded PKIX X.509 certificatex509: DER encoded PKIX X.509 certificatepem: PEM encoded of PKCS8 / SPKI / PKIXGrant public methods accept a request config as the last argument,
to allow specifying headers and timeout per-request (in seconds):access_token=oid_client.grant_client(scopes=["scope1"],headers={'X-Correlator':'1234-5678-9012-3456-7890'},timeout=30)If you are using the library against a Telefónica Kernel development environment, you can accept self-signed certs setting this environment variable:export BAIKAL_VERIFY_CERTS=False  # Accept self signed certs for authserver communication (not used in token validation)Configure asynchronous connectionsAIOHTTP_SESSION_SIZE: max # of requests per session. By default 200.AIOHTTP_SESSION_DNS_CACHE: TTL of dns sessions. By default 20.AIOHTTP_SESSION_LIMIT: Total number of opened connections. By default 500.Generate private keysIt's not needed to have private keys generated from a secured authority. For oauth2 verify you can use self-generated keys. Here it's included some tips.If you want to generate different keys (in JWK format) for development purpose you can usehttps://mkjwk.org/.Generate a RSA private key (with SHA 256 hash, RS256) (using openssl)opensslgenrsa-des3-outprivate-rsa-protected.pem2048This will produce a private rsa key of 2048 bits protected with a password, in order to remove the password and use directly the private key in the library you can run this:opensslrsa-inprivate-rsa-protected.pem-outprivate-rsa.pem# rm private-rsa-protected.pemAnother option (single line) is to use this command:opensslgenpkey-outrsakey.pem-algorithmRSA-pkeyoptrsa_keygen_bits:2048The private-rsa.pem can be used with the library to generate assertions and to expose the public key part as stated before. Just place the pem in your directory and point the sdk private_certs_path to it.
The public key is automatically generated in JWK as you can check in the expose your public keys section.It's not recommended to use rsa keys bigger than 2048 (e.g 4096) as the computational cost is not worth.
It's better to have a keys rotation policy every given time (e.g. a week).
It's also not recommended to use keys of 1024 length as it can be cracked.