This SDK will let you execute all the API methods, version/2, described at https://developers.onelogin.com/api-docs/2/getting-started/dev-overview.
The SDK also covers common use cases with OneLogin including PKCE and Smart MFA integration with React, Angular and Vue.
This module is under development and accepting PRs from the community.
You'll need a OneLogin account and a set of API credentials before you get started.
If you don't have an account you can sign up for a free developer account here.
From the admin panel of your OneLogin account, select Developers > API Credentials and click New Credential to create an API credential.
| Value | Description |
|---|---|
| client_id | Required unless using for frontend (see PKCE): A valid OneLogin API client_id |
| client_secret | Required unless using for frontend (see PKCE): A valid OneLogin API client_secret |
| region | Optional if not using baseURL: 'us' or 'eu'. |
| baseURL | Optional if not using a region: Should look like https://api.<region>.onelogin.com |
Currently this SDK supports the following resources:
| Resource | Description | Docs |
|---|---|---|
| Apps | The OneLogin App Resource (e.g. an OIDC or SAML application) | https://developers.onelogin.com/api-docs/2/apps/overview |
| Users | Representation of a User in OneLogin | https://developers.onelogin.com/api-docs/2/users/overview |
import Client from "@onelogin/sdk";
const onelogin = new Client({
clientID: abc-123-def-456,
clientSecret: 654-fed-321-cba,
region: "us"
});
let newApp = onelogin.apps.Create({
name: "new app",
connector_id: 123
}) // creates a new SAML app
newApp.name= "updated app"
onelogin.apps.Update(newApp) // updates the app in OneLogin
let apps = onelogin.apps.Query() // list all apps
let samlApps = onelogin.apps.Query({connector_id: 123}) // list SAML apps (connector_id = 123)
let awsApp = onelogin.apps.FindByID(newApp.ID) // aws app with id = 123
onelogin.apps.Destroy(newApp.ID) // destroys the app in OneLogin
This SDK supports integrating OneLogin as the IdP for PKCE https://developers.onelogin.com/blog/pkce-dust-react-app
PKCE is a useful auth flow for apps that don't have a secure means for storing client secret and prevents auth_code intercept attacks https://tools.ietf.org/html/rfc7636
For this flow, you'll need to create a OIDC App in OneLogin and configure it to use PKCE in the SSO setting by setting the Token Endpoint value to None (PKCE)
Then, note down the Client ID for the app (different from the OneLogin API credential Client ID)
Finally under Configuration, specify one or more redirect urls to be allowed. http://localhost:3000 is also allowed for local development.
import Client from "@onelogin/sdk";
const onelogin = new Client({region: "us"}); // client id and secret are not required here
let pkceClient = onelogin.pkce.Configure({
redirectURL: "http://localhost:3000",
clientID: oidc-123-client-3456
});
let loginLink = document.getElementById("loginLink") // some <a> tag
pkceClient.CreateAuthURL().then(url => loginLink.href = url) // establish link for user to click to go to login page
let accessToken = ""
let urlParams = new URLSearchParams(location.search);
let code = urlParams['code']; // code returned after successful login
pkceClient.GetAccessTokenAsync(code).then(token => accessToken = token)
let me = null
pkceClient.GetUserInfoAsync(accessToken).then(user => me = user)
This SDK comes with the methods required to support the Smart MFA scenario. This scenario checks a User's behavior analytics with Vigilance A.I. to determine if an additional factor such as Email or SMS is required.
Generally one of 2 things should happen:
- User is checked against Vigilance and no action required
- User is checked but requires additional factor. In this case you'll get a MFA token in the response of the
CheckMFARequiredfunction to validate later.
- Finally as shown in
/otpwe combine the MFA token with the supplied OTP collected from the client and use that to determine if a user has rightful access
const onelogin = new Client({
clientID: abc-123-def-456,
clientSecret: 654-fed-321-cba,
region: "us"
});
// implement these routes
router.post('/signup', signupRoute)
router.post('/login', loginRoute)
router.post('/otp', otpRoute)
signupRoute = async (req: Request, res: Response) => {
try {
let existingUser = this.userDB.Read(req.body.email)
if( existingUser ) {
return res.status(400).json({
error: `User with id ${req.body.email} exists!`
})
}
let { email: user_identifier, phone, password } = req.body
let context = {
user_agent: req.headers["user-agent"],
ip: req.connection.remoteAddress
}
let { data, error } = await onelogin.smartMFA.CheckMFARequired({
user_identifier, phone, context
})
if( error ) return res.status(error.httpStatusCode).json(error.data)
this.userDB.Upsert({
phone,
password,
id: user_identifier,
email: user_identifier
})
console.log(`Completed Risk Assessment for ${user_identifier}`)
return res.status(200).json(data.mfa)
} catch( err ) {
console.log("An unknown error occurred", err)
return res.status(500).send(err.message)
}
}
loginRoute = async (req: Request, res: Response) => {
try {
let user = this.userDB.Read(req.body.email)
if( !user ) {
return res.status(400).json({
error: `User with id ${req.body.email} not found!`
})
}
if( !user.validated(req.body.password) ) {
return res.status(400).json({ error: `Wrong password` })
}
let { email: user_identifier, phone } = user
let context = {
user_agent: req.headers["user-agent"],
ip: req.connection.remoteAddress
}
let { data, error } = await onelogin.smartMFA.CheckMFARequired({
user_identifier, phone, context
})
if( error ) return res.status(error.httpStatusCode).json(error.data)
console.log(`Completed Risk Assessment for ${user_identifier}`)
return res.status(200).json(data.mfa)
} catch( err ) {
console.log("An unknown error occurred", err)
return res.status(500).send(err.message)
}
}
otpRoute = async (req: Request, res: Response) => {
try {
let data = await onelogin.smartMFA.ValidateOTP( { ...req.body } )
console.log("OTP Validation Done!")
return res.status(200).json(data)
} catch( err ) {
console.log("An unknown error occurred", err)
return res.status(500).send(err.message)
}
}