Passport.js docs 일부 번역

Documentation

 

passport의 명확한 이해를 위해 문서를 일부 번역해보았습니다. Provider와 같은 specific한 부분보다는 Overview부터 User Profile까지 passport의 근본적인 원리를 담고 있는 부분만 번역했습니다.

 

 

🎩 개요(Overview)
🎩 인증(Authenticate)
  🧷 리다이렉션(Redirection)
  🧷플래시 메세지(Flash Messages)
  🧷 세션 비활성화(Disable Sessions)
  🧷 커스텀 콜백(Custom Callback)
🎩 설정 (Configure)
  🧷 전략 (Strategy)
  🧷 검증 콜백(Verify Callback)
  🧷 미들웨어 
🎩 아이디와 비밀번호 Username & Password
  🧷 설정 (Configuration)
  🧷 폼 (Form)
  🧷 Route
  🧷 Parameters

 

 

---

 

 

🎩 개요(Overview)

 

passport.js는 노드에서 사용하는 인증용 미들웨어입니다. passport.js는 오로지 한 가지 목적을 위해 디자인 되었습니다. 그 목적은, 요청(request)를 인증하는 것입니다. 모듈을 디자인할 때 캡슐화를 하는 것이 코드를 작성하는 데 편리하므로 passport.js 또한 모든 기능을 캡슐화하였습니다. 이러한 방식은 코드를 깔끔하게 유지하고 어플리케이션에 passport를 통합하는 것을 쉽게 만들어줍니다.

 

모던한 웹앱에서는 인증 수단은 매우 다양한 형태로 이루어질 수 있습니다. 전통적으로, 유저는 유저네임(아이디)와 비밀번호를 제공함으로써 로그인을 했습니다만, SNS가 대세가 되면서 OAuth 제공자(Facebook, Twitter etc...)를 경유한 single sign on(SSO)이 대중적인 인증 수단이 되었습니다. API를 노출하는 서비스는 종종 토큰을 기반으로한 자격 증명을 요구하기도 합니다. 

 

passport.js는 각각의 어플리케이션이 고유한 인증 방식을 가지고 있다는 것을 인지하고 있습니다. 인증 방식의 매커니즘(Strategy라고 합니다)은 개별적인 모듈로 패키지 되었습니다.* 덕분에 여러분들은 불필요한 의존성 패키지(dependencies)를 만들지 않고도 어떤 Strategy를 사용할 것인지를 선택할 수 있습니다. 

 

* Strategy 페이지에서 passport-facebook, passport-github 등 개별적인 모듈로 패키지된 것을 확인할 수 있습니다.

 

인증 과정의 복잡함에도 불구하고 코드는 심플하게 작성할 수 있습니다.

 

 

 

 

 

🎩 인증(Authenticate)

 

인증 요청은 passport.authenticate()를 호출하고 무슨 전략을 사용할 것지를 결정하는 것만큼 쉽습니다. authenticate() 함수는 일반적인 미들웨어로, express 프레임워크에서 미들웨어로 사용하기에 편리합니다.

 

 

 

기본적으로, 인증이 실패하면, 401 상태코드를 응답하고 콜백함수가 호출되지 않습니다. 만약 인증이 성공하면 다음의 함수(콜백함수)가 호출되고 req.user에 인증된 유저 정보가 담깁니다.

 

Note : 전략은 미들웨어에서 사용되기 전에 구성(Config)되어야합니다. 이후에 더 자세히 설명합니다.

 

🧷 리다이렉션(Redirection)

 

일반적으로 리다이렉션은 인증 요청 이후에 실행됩니다.

 

 

 

위의 경우 리다이렉션 옵션은 기본에 오버라이드됩니다. 인증에 성공하면 유저는 /(home page)로 리다이렉션되며 인증 실패시 다시 로그인하기 위해 /login으로 리다이렉션 됩니다.

 

 

🧷플래시 메세지(Flash Messages)

 

리다이렉션은 종종 유저에게 상태 정보를 알려주기 위해 플래시 메모리와 같이 사용됩니다. (예를 들어 비밀번호가 잘못되었습니다. 아이디 정보가 없습니다 등...)

 

 

 

failureFlash를 true로 설정하면 passport의 전략을 체크하는 콜백 함수에서 제공하는 메세지가 있는 경우 오류 메세지를 flash하도록 지시합니다. 

 

대신에, 직접 메세지를 적어 줄 수도 있으며, 성공 flash도 가능합니다.

 

 

Note : 플래시 메세지를 사용하기 위해서는 req.flash()가 필요합니다. Express 2.x 버전은 기본적으로 제공했지만 3.x부터는 제거되었으므로 connect-flash를 설치하여 미들웨어로 설정해야 합니다. app.use(flash());

 

🧷 세션 비활성화(Disable Sessions)

 

인증을 성공한 후에는 passport.js는 영구 로그인 세션(persistent login session)을 구성합니다. 이 방식은 브라우저를 통해 웹앱에 접속하는 일반적인 시나리오에서 유용합니다. 그러나 몇몇 경우에는 세션을 사용하는 것이 불필요한 경우가 있습니다. 예를 들면, API 서버는 각 요청때마다 인증을 요구합니다. 이 경우에는 세션 사용하지 않음으로서 안전하게 세션 기능을 끌 수 있습니다.

 

 

🧷 커스텀 콜백(Custom Callback)

 

내장된 옵션이 인증 요청을 핸들링하는데 충분하지 않다면 콜백 함수를 만들어 활용할 수 있습니다. (대개 이 방법을 사용합니다.)

 

 

위 예시에서 authenticate()는 미들웨어로 사용되지 않고 route 핸들러로 사용되었습니다. 이 방식을 통해 클로저로 req, res 객체에 접근할 수 있습니다.

 

만약 인증이 실패하면 유저는 false로 설정됩니다. 예외가 일어나면 에러가 설정됩니다. 선택적 인자인 info는 추가적인 디테일을 포함하고 있습니다. 

 

이 콜백 함수는 제공된 인자를 통해 원하는 대로 인증 결과를 처리할 수 있습니다. 커스텀 콜백을 사용할 때는 세션을 구성하고(req.login()을 통해 할 수 있습니다) 응답을 보내는 것이 어플리케이션의 책임(자동으로 해주지 않음)인 것을 주의하십시오.

 

 

🎩 설정 (Configure)

 

인증을 위해 passport.js를 사용하려면 설정해야할 3가지가 있습니다.

 

1. Authentication strategies 인증 전략
2. Application middleware 미들웨어
3. Sessions (optional) 세션

 

 

🧷 전략 (Strategy)

 

인증 요청을 인증하기 위해 전략(Stragey)를 사용합니다. 전략은 아이디와 비민번호를 확인하는 것에서부터 OAuth를 사용한 인증이나 소셜 로그인(federated authentication) 까지 다양한 것을 이릅니다.

 

앞서 인증 요청을 보내기 전에 전략을 configure해야 한다고 했습니다. 전략과 그 구성은, use() 함수에 의해 설정됩니다. 예를 들면, 다음의 예시는 아이디와 비밀번호를 활용한 local 전략입니다.

 

 

 

🧷 검증 콜백(Verify Callback)

흔히 done, cb로 처리하는 그 함수입니다.

 

이 예시는 중요한 컨셉을 소개합니다. 전략은 "검증 콜백"(verify callback)이란 것이 필요합니다. 검증 콜백의 목적은 자격을 가진(인증을 통과한) 유저를 찾는 것입니다.

 

인증 요청이 들어오면 passport는 해당 정보를 파싱한 다음 그 정보를 인자로 콜백 함수를 호출합니다. 이 예시에서는 아이디와 비밀번호입니다. 만약 인증 요청이 유효하다면 검증 콜백은 인증된 사용자와 함께 Passport를 제공하기 위해 수행된 작업을 수행합니다.

 

return done(null, user);

 

인증 정보가 유효하지 않은 경우(예: 암호가 올바르지 않은 경우), 인증 실패를 나타내는 사용자 대신 false로 호출해야 합니다.

return done(null, false);

 

실패한 이유에 대해서 추가적인 메세지를 보낼 수도 있습니다. 유저에게 다시 로그인을 시도해보라고 플래시 메세지를 보낼 때 유용합니다.

return done(null, false, { message: 'Incorrect password.' });

 

만약 인증 도중 오류가 발생했을 때는 done 함수는 에러를 호출해야 합니다.

return done(err);

 

🧷 미들웨어 

 

Express 기반 어플리케이션에서 passport를 사용하기 위해선 passport.initialize() 미들웨어가 필요합니다. 만약 영구 로그인 세션(persistent login sessions)을사용한다면 passport.session() 미들웨어 또한 반드시 사용되어야 합니다.

 

 

물론, session 사용은 선택적입니다. (그래도 대부분의 애플리케이션에서 사용됩니다) passport에서 session을 사용하기 위해서는 먼저 express.session()을 사용해야 합니다. 미들웨어의 순서에 주의합시다.

 

세션에 대해서 조금 더 자세하게 알아봅시다.

 

일반적인 웹앱에서 사용자 인증에 사용되는 자격 증명은 로그인 요청 중에만 전송된다. 인증에 성공하면 사용자의 브라우저에 있는 쿠키를 통해 세션이 설정되고 유지됩니다. 이후의 요청은 자격 증명이 아니라 쿠키를 통해 이루어집니다. 로그인 세션을 지원하기 위해서 passport는 유저 인스턴스를 serialize 및 deserialize한다.

 

* serialize란 req.session 객체에 무엇을 저장할 것인지를 선택하는 것입니다. 세션에 모든 정보를 저장하는 것은 세션의 용량을 너무 크게 만드므로 대개 user의 id만을 저장합니다. deserialize는 serialize를 통해 받은 유저의 id를 이용해 이용자를 식별하는 것입니다.

 

 

위 예시에서는 id만 serialize, 즉, 세션에 저장해서 세션의 데이터 양을 작게 유지합시다. 그 후의 요청을 받게 되면 이 id가 유저를 식별하는데 이용됩니다. 

 

 

🎩 아이디와 비밀번호 Username & Password

 

가장 흔히 사용되는 인증 방식은 유저 네임(아이디)와 비밀번호입니다. 이 방식의 전략은 "local"이라는 모듈에 의해 제공됩니다.

 

npm i passport-local

 

🧷 설정 (Configuration)

 

로컬 인증을 위한 검증 콜백(verify callback)은 아이디와 비밀번호 인자를 받습니다. 이 인자를 HTML form을 통해 전달받습니다. 

 

🧷 폼 (Form)

<form action="/login" method="post">
    <div>
        <label>Username:</label>
        <input type="text" name="username"/>
    </div>
    <div>
        <label>Password:</label>
        <input type="password" name="password"/>
    </div>
    <div>
        <input type="submit" value="Log In"/>
    </div>
</form>

 

🧷 Route

로그인 form은 POST로 서버에 전달됩니다. authenticate()를 통해 로그인 요청을 핸들링해봅시다.

 

 

🧷 Parameters

 

기본값으로 local 전략은 username과 password라는이름의 파라미터를 찾습니다. 만약 다른 방식으로 input 태그의 name을 설정했다면 다른 방식으로 설정해줄 수 있습니다.

 

 

 

🎩 소셜로그인(OpenID)

 

OpenID는 federated authentication의 표준입니다. 웹 사이트를 방문할 때 유저는 OpenID를 통해 회원가입을 할 수 있습니다. 유저는 provider로부터 인증을 받습니다.

 

이 부분은 구체적인 strategy를 통해 살펴보는 것이 더 좋으니 생략하도록 하겠습니다. 가장 쉬운 인증으로는 kakao나 github가 있습니다만, kakao 전략은 한글로 작성되어 있으므로 kakao로 시작하는 것이 좋다고 생각합니다.

 

passport.js : (3) kakao 로그인

 

이후의 내용은 Provider를 다루고 있습니다. 이후에 시간이 되면 Provider 부분을 번역해보도록 하겠습니다. 끝!