Looker가 싱글 사인온 (SSO) 삽입을 사용하여 iframe에 삽입되면 일부 브라우저에서는 기본적으로 서드 파티 쿠키를 차단하는 쿠키 정책을 사용합니다. 삽입된 iframe이 삽입 애플리케이션을 로드하는 도메인과 다른 도메인에서 로드되는 경우 서드 파티 쿠키가 거부됩니다. 일반적으로 가상 도메인을 요청하고 사용하여 이 제한을 해결할 수 있습니다. 하지만 가상 도메인은 일부 시나리오에서 사용할 수 없습니다. 이러한 경우에는 Looker 쿠키가 없는 임베딩을 사용할 수 있습니다.
쿠키가 없는 임베딩은 어떻게 작동하나요?
서드 파티 쿠키가 차단되지 않으면 사용자가 처음에 Looker에 로그인할 때 세션 쿠키가 생성됩니다. 이 쿠키는 모든 사용자 요청과 함께 전송되며 Looker 서버에서 쿠키를 사용하여 요청을 시작한 사용자의 ID를 설정합니다. 쿠키가 차단되면 쿠키가 요청과 함께 전송되지 않으므로 Looker 서버에서 요청과 연결된 사용자를 식별할 수 없습니다.
이 문제를 해결하기 위해 Looker 쿠키가 없는 삽입은 Looker 서버에서 사용자 세션을 다시 만드는 데 사용할 수 있는 토큰을 각 요청과 연결합니다. 임베딩 애플리케이션은 이러한 토큰을 가져와서 삽입된 iframe에서 실행 중인 Looker 인스턴스에 제공해야 합니다. 이 토큰을 얻고 제공하는 프로세스는 이 문서의 나머지 부분에 설명되어 있습니다.
Looker 삽입 iframe 만들기
다음 시퀀스 다이어그램은 삽입된 iframe의 생성을 보여줍니다. 여러 iframe이 동시에 또는 나중에 생성될 수 있습니다. 제대로 구현하면 iframe이 첫 번째 iframe에서 만든 세션에 자동으로 참여합니다. Looker Embed SDK는 자동으로 기존 세션에 참여하여 이 프로세스를 간소화합니다.
- 사용자는 임베딩 애플리케이션에서 Looker iframe을 생성하는 작업을 수행합니다.
- 임베딩 애플리케이션 클라이언트는 Looker 세션을 획득합니다. Looker Embed SDK를 사용하여 이 세션을 시작할 수 있지만 엔드포인트 URL 또는 콜백 함수를 제공해야 합니다. 콜백 함수를 사용하면 임베딩 애플리케이션 서버를 호출하여 Looker 임베딩 세션을 획득합니다. 그렇지 않으면 삽입 SDK가 제공된 엔드포인트 URL을 호출합니다.
- 임베딩 애플리케이션 서버는 Looker API를 사용하여 임베딩 세션을 가져옵니다. 이 API 호출은 Looker SSO 서명 프로세스와 유사합니다. 삽입 사용자 정의를 입력으로 받기 때문입니다. 호출하는 사용자에게 이미 Looker 삽입 세션이 있는 경우 연결된 세션 참조 토큰을 호출에 포함해야 합니다. 이에 대해서는 이 문서의 세션 획득 섹션에서 자세히 설명합니다.
- 삽입 세션 가져오기 엔드포인트 처리는 URL이 아닌 요청 본문으로 Looker 삽입 사용자 정의를 예상한다는 점에서 SSO 서명
/login/embed/{signed url)엔드포인트와 유사합니다. 삽입 세션 획득 엔드포인트 프로세스는 삽입 사용자를 검증하고 생성 또는 업데이트합니다. 기존 세션 참조 토큰도 사용할 수 있습니다. 이렇게 하면 Looker에서 삽입된 여러 iframe이 동일한 세션을 공유할 수 있습니다. 세션 참조 토큰이 제공되었으며 세션이 만료되지 않은 경우 삽입 사용자는 업데이트되지 않습니다. 이는 서명된 SSO URL을 사용하여 하나의 iframe을 만들고 서명된 SSO URL 없이 다른 iframe을 만드는 사용 사례를 지원합니다. 이 경우 서명된 SSO URL이 없는 iframe이 첫 번째 세션의 쿠키를 상속합니다. - Looker API 호출은 토큰을 TTL (수명)과 함께 4개 반환합니다.
- 승인 토큰 (TTL = 30초)
- 탐색 토큰 (TTL = 10분)
- API 토큰 (TTL = 10분)
- 세션 참조 토큰 (TTL = 세션의 전체 기간)
- 임베딩 애플리케이션 서버는 Looker 데이터에서 반환된 데이터를 추적하고 이를 호출하는 사용자 및 호출하는 사용자 브라우저의 사용자 에이전트 모두와 연결해야 합니다. 이 방법에 대한 제안은 이 문서의 토큰 생성 섹션에 나와 있습니다. 이 호출은 모든 관련 TTL과 함께 승인 토큰, 탐색 토큰, API 토큰을 반환합니다. 세션 참조 토큰은 보호되어야 하며 호출 브라우저에 노출되지 않아야 합니다.
토큰이 브라우저에 반환되면 Looker 삽입 로그인 URL을 구성해야 합니다. Looker Embed SDK가 삽입 로그인 URL을 자동으로 구성합니다.
windows.postMessageAPI를 사용하여 삽입 로그인 URL을 구성하려면 이 문서의 Lookerwindows.postMessageAPI 사용 섹션에서 예를 확인하세요.로그인 URL에 서명된 삽입 사용자 세부정보가 포함되어 있지 않습니다. 탐색 토큰을 비롯한 대상 URI와 쿼리 매개변수로 승인 토큰을 포함합니다. 승인 토큰은 30초 이내에 사용되어야 하며 한 번만 사용할 수 있습니다. 추가 iframe이 필요한 경우 삽입 세션을 다시 획득해야 합니다. 하지만 세션 참조 토큰이 제공되면 승인 토큰이 동일한 세션과 연결됩니다.
Looker 삽입 로그인 엔드포인트는 로그인 시 승인 토큰이 있음을 나타내는 쿠키가 없는 삽입에 대한 로그인인지 판단합니다. 승인 토큰이 유효한 경우 다음을 확인합니다.
- 연결된 세션이 아직 유효합니다.
- 연결된 삽입 사용자가 계속 유효합니다.
- 요청과 연결된 브라우저 사용자 에이전트가 세션과 연결된 브라우저 에이전트와 일치합니다.
이전 단계의 확인이 통과되면 URL에 포함된 대상 URI를 사용하여 요청이 리디렉션됩니다. 이는 Looker Embed SSO 로그인과 동일한 프로세스입니다.
이 요청은 Looker 대시보드를 실행하기 위한 리디렉션입니다. 이 요청에는 매개변수로 탐색 토큰이 있습니다.
엔드포인트가 실행되기 전에 Looker 서버는 요청에서 탐색 토큰을 찾습니다. 서버에서 토큰을 찾으면 다음을 확인합니다.
- 연결된 세션이 아직 유효합니다.
- 요청과 연결된 브라우저 사용자 에이전트가 세션과 연결된 브라우저 에이전트와 일치합니다.
유효하면 요청의 세션이 복원되고 대시보드 요청이 실행됩니다.
대시보드를 로드하는 HTML이 iframe으로 반환됩니다.
iframe에서 실행되는 Looker UI에서 대시보드 HTML이 쿠키가 없는 삽입 응답임을 확인합니다. 이 시점에 Looker UI가 6단계에서 검색한 토큰을 요청하는 메시지를 임베딩 애플리케이션에 전송합니다. 그러면 UI가 토큰을 받을 때까지 기다립니다. 토큰이 도착하지 않으면 메시지가 표시됩니다.
임베딩 애플리케이션은 토큰을 Looker에 삽입된 iframe으로 전송합니다.
토큰이 수신되면 iframe에서 실행 중인 Looker UI가 요청 객체를 렌더링하는 프로세스를 시작합니다. 이 과정에서 UI는 Looker 서버에 API를 호출합니다. 15단계에서 수신한 API 토큰이 모든 API 요청에 자동으로 헤더로 삽입됩니다.
엔드포인트가 실행되기 전에 Looker 서버는 요청에서 API 토큰을 찾습니다. 서버는 토큰을 찾으면 다음을 확인합니다.
- 연결된 세션이 아직 유효합니다.
- 요청과 연결된 브라우저 사용자 에이전트가 세션과 연결된 브라우저 에이전트와 일치합니다.
세션이 유효하면 요청이 복원되고 API 요청이 실행됩니다.
대시보드 데이터가 반환됩니다.
대시보드가 렌더링됩니다.
사용자는 대시보드를 제어할 수 있습니다.
새 토큰 생성
- 삽입된 iframe에서 실행 중인 Looker UI가 삽입된 토큰의 TTL을 모니터링합니다.
- 토큰이 만료될 때 Looker UI가 임베딩 애플리케이션 클라이언트에 갱신 토큰 메시지를 보냅니다.
- 그런 다음 임베딩 애플리케이션 클라이언트가 임베딩 애플리케이션 서버에 구현된 엔드포인트에서 새 토큰을 요청합니다. Looker 삽입 SDK는 새 토큰을 자동으로 요청하지만 엔드포인트 URL 또는 콜백 함수를 제공해야 합니다. 콜백 함수를 사용하면 임베딩 애플리케이션 서버를 호출하여 새 토큰을 생성합니다. 그렇지 않으면 삽입 SDK가 제공된 엔드포인트 URL을 호출합니다.
- 임베딩 애플리케이션은 삽입 세션과 연결된
session_reference_token를 찾습니다. Looker Embed SDK Git 저장소에 제공된 예에서는 세션 쿠키를 사용하지만, 분산 서버 측 캐시(예: Redis)도 사용할 수 있습니다. - 임베딩 애플리케이션 서버는 토큰 생성 요청을 사용하여 Looker 서버를 호출합니다. 또한 이 요청에는 요청을 시작한 브라우저의 사용자 에이전트 외에 최신 API 및 탐색 토큰도 필요합니다.
- Looker 서버는 사용자 에이전트, 세션 참조 토큰, 탐색 토큰, API 토큰을 검증합니다. 요청이 유효하면 새 토큰이 생성됩니다.
- 토큰은 호출 삽입 애플리케이션 서버로 반환됩니다.
- 임베딩 애플리케이션 서버는 응답에서 세션 참조 토큰을 제거하고 임베딩 애플리케이션 클라이언트에 나머지 응답을 반환합니다.
- 임베딩 애플리케이션 클라이언트는 새로 생성된 토큰을 Looker UI로 전송합니다. Looker Embed SDK에서 이 작업을 자동으로 실행합니다.
windows.postMessageAPI를 사용하는 애플리케이션 클라이언트를 삽입하면 토큰이 전송됩니다. Looker UI에서 토큰을 받으면 후속 API 호출 및 페이지 탐색에 사용됩니다.
Looker 쿠키가 없는 삽입 구현
Looker Embed SDK 또는 windows.postMessage API를 사용하여 Looker 쿠키가 없는 삽입을 구현할 수 있습니다. Looker Embed SDK를 사용하는 메서드가 더 쉽지만 windows.postMessage API를 사용하는 방법을 보여주는 예도 사용할 수 있습니다. 두 구현 모두에 관한 자세한 설명은 Looker Embed SDK README 파일에서 확인할 수 있습니다. Embed SDK git 저장소에는 작동하는 구현도 포함되어 있습니다.
Looker 인스턴스 구성
쿠키가 없는 임베딩은 Looker 싱글 사인온 (SSO) 임베딩과 공통점이 있습니다. 쿠키가 없는 임베딩은 SSO SSO 인증이 사용 설정되어 있어야 작동합니다. 그러나 Looker SSO와 달리 쿠키 없는 임베딩은 Embed Secret 설정을 사용하지 않습니다. 쿠키가 없는 삽입은 JWT 보안 비밀 설정 형식으로 JSON 웹 토큰 (JWT)을 사용하며, 이 양식은 관리 메뉴의 플랫폼 섹션에 있는 삽입 페이지에서 설정하거나 재설정할 수 있습니다.
쿠키가 없는 삽입 세션을 처음 만들면 JWT가 생성되므로 JWT 보안 비밀을 설정할 필요가 없습니다. 이 토큰을 재설정하면 쿠키가 없는 활성 삽입 세션이 모두 무효화됩니다.
삽입 보안 비밀과 달리 삽입 JWT 보안 비밀은 Looker 서버에서 내부적으로만 사용되므로 노출되지 않습니다.
애플리케이션 클라이언트 구현
이 섹션에는 애플리케이션 클라이언트에서 쿠키 없는 임베딩을 구현하는 방법의 예와 다음 하위 섹션이 포함되어 있습니다.
Looker Embed SDK 설치 또는 업데이트
쿠키가 없는 삽입을 사용하려면 다음 Looker SDK 버전이 필요합니다.
@looker/embed-sdk >= 1.8
@looker/sdk >= 22.16.0
Looker Embed SDK 사용
쿠키가 없는 세션을 시작할 수 있도록 새로운 초기화 메서드가 Embed SDK에 추가되었습니다. 이 메서드는 2개의 URL 문자열 또는 2개의 콜백 함수를 허용합니다. URL 문자열은 임베딩 애플리케이션 서버의 엔드포인트를 참조해야 합니다. 애플리케이션 서버에서 이러한 엔드포인트의 구현 세부정보는 이 문서의 애플리케이션 서버 구현 섹션에서 다룹니다.
LookerEmbedSDK.initCookieless(
runtimeConfig.lookerHost,
'/acquire-embed-session',
'/generate-embed-tokens'
)
다음 예에서는 콜백이 사용되는 방식을 보여줍니다. 콜백은 임베딩 클라이언트 애플리케이션에서 Looker 임베딩 세션의 상태를 인식해야 하는 경우에만 사용해야 합니다. session:status 이벤트를 사용할 수도 있으므로 삽입 SDK에서 콜백을 사용할 필요가 없습니다.
const acquireEmbedSessionCallback =
async (): Promise<LookerEmbedCookielessSessionData> => {
const resp = await fetch('/acquire-embed-session')
if (!resp.ok) {
console.error('acquire-embed-session failed', { resp })
throw new Error(
`acquire-embed-session failed: ${resp.status} ${resp.statusText}`
)
}
return (await resp.json()) as LookerEmbedCookielessSessionData
}
const generateEmbedTokensCallback =
async (): Promise<LookerEmbedCookielessSessionData> => {
const { api_token, navigation_token } = getApplicationTokens() || {}
const resp = await fetch('/generate-embed-tokens', {
method: 'PUT',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ api_token, navigation_token }),
})
if (!resp.ok) {
if (resp.status === 400) {
return { session_reference_token_ttl: 0 }
}
console.error('generate-embed-tokens failed', { resp })
throw new Error(
`generate-embed-tokens failed: ${resp.status} ${resp.statusText}`
)
}
return (await resp.json()) as LookerEmbedCookielessSessionData
}
LookerEmbedSDK.initCookieless(
runtimeConfig.lookerHost,
acquireEmbedSessionCallback,
generateEmbedTokensCallback
)
Looker windows.postMessage API 사용
Embed SDK Git 저장소의 message_example.ts 및 message_utils.ts 파일에서 windows.postMessage API를 사용하는 자세한 예를 확인할 수 있습니다. 주요 예시는 아래에 나와 있습니다.
다음 예는 iframe의 URL을 빌드하는 방법을 보여줍니다. 콜백 함수는 이전에 본 acquireEmbedSessionCallback 예와 동일합니다.
private async getCookielessLoginUrl(): Promise<string> {
const { authentication_token, navigation_token } =
await this.embedEnvironment.acquireSession()
const url = this.embedUrl.startsWith('/embed')
? this.embedUrl
: `/embed${this.embedUrl}`
const embedUrl = new URL(url, this.frameOrigin)
if (!embedUrl.searchParams.has('embed_domain')) {
embedUrl.searchParams.set('embed_domain', window.location.origin)
}
embedUrl.searchParams.set('embed_navigation_token', navigation_token)
const targetUri = encodeURIComponent(
`${embedUrl.pathname}${embedUrl.search}${embedUrl.hash}`
)
return `${embedUrl.origin}/login/embed/${targetUri}?embed_authentication_token=${authentication_token}`
}
다음 예시에서는 토큰 요청을 수신 대기하고 새 토큰을 생성하여 Looker로 전송하는 방법을 보여줍니다. 콜백 함수는 이전의 generateEmbedTokensCallback 예와 동일합니다.
this.on(
'session:tokens:request',
this.sessionTokensRequestHandler.bind(this)
)
private connected = false
private async sessionTokensRequestHandler(_data: any) {
const contentWindow = this.getContentWindow()
if (contentWindow) {
if (!this.connected) {
// When not connected the newly acquired tokens can be used.
const sessionTokens = this.embedEnvironment.applicationTokens
if (sessionTokens) {
this.connected = true
this.send('session:tokens', this.embedEnvironment.applicationTokens)
}
} else {
// If connected, the embedded Looker application has decided that
// it needs new tokens. Generate new tokens.
const sessionTokens = await this.embedEnvironment.generateTokens()
this.send('session:tokens', sessionTokens)
}
}
}
send(messageType: string, data: any = {}) {
const contentWindow = this.getContentWindow()
if (contentWindow) {
const message: any = {
type: messageType,
...data,
}
contentWindow.postMessage(JSON.stringify(message), this.frameOrigin)
}
return this
}
애플리케이션 서버 구현
이 섹션에는 애플리케이션 서버에서 쿠키 없는 임베딩을 구현하는 방법에 대한 예시가 포함되어 있으며 다음과 같은 하위 섹션이 있습니다.
기본 구현
임베딩 애플리케이션은 Looker 엔드포인트를 호출하는 2개의 서버 측 엔드포인트를 구현하는 데 필요합니다. 세션 참조 토큰이 안전하게 유지되도록 하기 위함입니다. 엔드포인트는 다음과 같습니다.
- 세션 획득 - 세션 참조 토큰이 이미 있고 아직 활성 상태인 경우 세션에 대한 요청이 기존 세션에 참여합니다. 획득 세션은 iframe이 생성되면 호출됩니다.
- 토큰 생성 - Looker가 이 엔드포인트에 대한 호출을 주기적으로 트리거합니다.
세션 획득
TypeScript의 이 예에서는 세션을 사용하여 세션 참조 토큰을 저장하거나 복원합니다. 엔드포인트를 TypeScript에서 구현할 필요가 없습니다.
app.get(
'/acquire-embed-session',
async function (req: Request, res: Response) {
try {
const current_session_reference_token =
req.session && req.session.session_reference_token
const response = await acquireEmbedSession(
req.headers['user-agent']!,
user,
current_session_reference_token
)
const {
authentication_token,
authentication_token_ttl,
navigation_token,
navigation_token_ttl,
session_reference_token,
session_reference_token_ttl,
api_token,
api_token_ttl,
} = response
req.session!.session_reference_token = session_reference_token
res.json({
api_token,
api_token_ttl,
authentication_token,
authentication_token_ttl,
navigation_token,
navigation_token_ttl,
session_reference_token_ttl,
})
} catch (err: any) {
res.status(400).send({ message: err.message })
}
}
)
async function acquireEmbedSession(
userAgent: string,
user: LookerEmbedUser,
session_reference_token: string
) {
await acquireLookerSession()
try {
const request = {
...user,
session_reference_token: session_reference_token,
}
const sdk = new Looker40SDK(lookerSession)
const response = await sdk.ok(
sdk.acquire_embed_cookieless_session(request, {
headers: {
'User-Agent': userAgent,
},
})
)
return response
} catch (error) {
console.error('embed session acquire failed', { error })
throw error
}
}
토큰 생성
TypeScript의 이 예에서는 세션을 사용하여 세션 참조 토큰을 저장하거나 복원합니다. 엔드포인트를 TypeScript에서 구현할 필요가 없습니다.
토큰이 유효하지 않을 때 발생하는 400개의 응답을 처리하는 방법을 잘 알고 있어야 합니다. 이런 일이 발생해서는 안 되지만 그럴 경우에는 세션을 종료하는 것이 좋습니다.
app.put(
'/generate-embed-tokens',
async function (req: Request, res: Response) {
try {
const session_reference_token = req.session!.session_reference_token
const { api_token, navigation_token } = req.body as any
const tokens = await generateEmbedTokens(
req.headers['user-agent']!,
session_reference_token,
api_token,
navigation_token
)
res.json(tokens)
} catch (err: any) {
res.status(400).send({ message: err.message })
}
}
)
}
async function generateEmbedTokens(
userAgent: string,
session_reference_token: string,
api_token: string,
navigation_token: string
) {
if (!session_reference_token) {
console.error('embed session generate tokens failed')
// missing session reference treat as expired session
return {
session_reference_token_ttl: 0,
}
}
await acquireLookerSession()
try {
const sdk = new Looker40SDK(lookerSession)
const response = await sdk.ok(
sdk.generate_tokens_for_cookieless_session(
{
api_token,
navigation_token,
session_reference_token: session_reference_token || '',
},
{
headers: {
'User-Agent': userAgent,
},
}
)
)
return {
api_token: response.api_token,
api_token_ttl: response.api_token_ttl,
navigation_token: response.navigation_token,
navigation_token_ttl: response.navigation_token_ttl,
session_reference_token_ttl: response.session_reference_token_ttl,
}
} catch (error: any) {
if (error.message?.includes('Invalid input tokens provided')) {
// Currently the Looker UI does not know how to handle bad
// tokens. This should not happen but if it does expire the
// session. If the token is bad there is not much that that
// the Looker UI can do.
return {
session_reference_token_ttl: 0,
}
}
console.error('embed session generate tokens failed', { error })
throw error
}
구현 관련 고려사항
임베딩 애플리케이션은 세션 참조 토큰을 추적하고 안전하게 보호해야 합니다. 이 토큰은 삽입된 애플리케이션 사용자와 연결되어야 합니다. 임베딩 애플리케이션 토큰은 다음 방법 중 하나로 저장할 수 있습니다.
- 삽입된 애플리케이션 사용자의 세션
- 클러스터링된 환경에서 사용할 수 있는 서버 측 캐시
- 사용자와 연결된 데이터베이스 테이블
세션이 쿠키로 저장된 경우 쿠키를 암호화해야 합니다. 삽입 SDK 저장소의 예에서는 세션 쿠키를 사용하여 세션 참조 토큰을 저장합니다.
Looker 삽입 세션이 만료되면 삽입된 iframe에 대화상자가 표시됩니다. 이 시점에서 사용자는 삽입된 인스턴스에서 어떤 작업도 수행할 수 없습니다. 이 경우 session:status 이벤트가 생성되어 임베딩 애플리케이션이 삽입된 Looker 애플리케이션의 현재 상태를 감지하고 일종의 작업을 수행할 수 있습니다.
Looker 쿠키가 없는 삽입 예시 실행
삽입 SDK 저장소에는 간단한 삽입 애플리케이션을 구현하는 TypeScript로 작성된 간단한 노드 익스프레스 서버와 클라이언트가 포함되어 있습니다. 이전에 표시된 예는 이 구현에서 가져왔습니다. 다음 단계에서는 앞에서 설명한 대로 Looker 인스턴스가 쿠키가 없는 삽입을 사용하도록 구성되었다고 가정합니다.
다음과 같이 서버를 실행할 수 있습니다.
- Embed SDK 저장소 클론 —
git clone git@github.com:looker-open-source/embed-sdk.git - 디렉터리 변경 —
cd embed-sdk - 종속 항목 설치 —
npm install - 이 문서의 서버 구성 섹션에 표시된 대로 서버를 구성합니다.
- 서버 실행 —
npm run server
서버 구성
클론된 저장소의 루트에 .env 파일을 만듭니다 (.gitignore에 포함됨).
형식은 다음과 같습니다.
LOOKER_EMBED_HOST=your-looker-instance-url.com.
LOOKER_EMBED_API_URL=https://your-looker-instance-url.com
LOOKER_DEMO_HOST=localhost
LOOKER_DEMO_PORT=8080
LOOKER_EMBED_SECRET=embed-secret-from-embed-admin-page
LOOKER_CLIENT_ID=client-id-from-user-admin-page
LOOKER_CLIENT_SECRET=client-secret-from-user-admin-page
LOOKER_DASHBOARD_ID=id-of-dashboard
LOOKER_LOOK_ID=id-of-look
LOOKER_EXPLORE_ID=id-of-explore
LOOKER_EXTENSION_ID=id-of-extension
LOOKER_VERIFY_SSL=true